View mode: basic / threaded / horizontal-split · Log in · Help
May 04, 2005
Preferred style of comments in source code.
What was last consensus, gentlemen?

Java, doxygen flavour, C# or what?

Phobos has samples of all styles....

Personally I don't like them all because they are mostly non readable in 
source code,
but, yes, they produce  more or less good results in generated docs.
BTW: Do you know examples of useful generated docs?  (url will be 
appreciated)

I am going to use something extremely simple like:

/**  show - Shows tooltip window
- tt - ITooltip, reference to the implementation of ITooltip
  interface - source of tooltip text.
- screenPos - point, screen relative coordinates of the
  origin of the tooltip window.
= true - if window was shown, false - otherwise
**/
bool show(ITooltip tt, point screenPos) { ... }

this is human readable (I guess ) and could be used as a source of generated 
doc.

Any ideas?

==============================================
Seems like D *will* have a declarative UI (whatever it means) ahead of time:
I've almost finished with "springs" (vertical and horizontal)
See: http://terrainformatica.com/screenshots/harmonia1.png
And: http://terrainformatica.com/screenshots/HarmoniaDemo.zip

Andrew.
May 04, 2005
Re: Preferred style of comments in source code.
Andrew Fedoniouk wrote:
> What was last consensus, gentlemen?
> 
> Java, doxygen flavour, C# or what?
> 
> Phobos has samples of all styles....
> 
> Personally I don't like them all because they are mostly non readable in 
> source code,
> but, yes, they produce  more or less good results in generated docs.
> BTW: Do you know examples of useful generated docs?  (url will be 
> appreciated)
> 
> I am going to use something extremely simple like:
> 
> /**  show - Shows tooltip window
>  - tt - ITooltip, reference to the implementation of ITooltip
>    interface - source of tooltip text.
>  - screenPos - point, screen relative coordinates of the
>    origin of the tooltip window.
>  = true - if window was shown, false - otherwise
>  **/
> bool show(ITooltip tt, point screenPos) { ... }
> 
> this is human readable (I guess ) and could be used as a source of generated 
> doc.
> 
> Any ideas?
> 
> ==============================================
> Seems like D *will* have a declarative UI (whatever it means) ahead of time:
> I've almost finished with "springs" (vertical and horizontal)
> See: http://terrainformatica.com/screenshots/harmonia1.png
> And: http://terrainformatica.com/screenshots/HarmoniaDemo.zip
> 
> Andrew. 
> 
> 

I might have missed this in the forums:  is harmonia available on Linux 
as well?

-JJR
May 04, 2005
Re: Preferred style of comments in source code.
Did you see Charlie's recent post about natural docs (www.naturaldocs.org) ?
Here's a sample on how to document: 
http://www.naturaldocs.org/documenting.html

Seems pretty readable, doesn't it?
The downside is, there's no current support for D...


Pablo

"Andrew Fedoniouk" <news@terrainformatica.com> wrote in message 
news:d5bc5i$2pd6$1@digitaldaemon.com...
> What was last consensus, gentlemen?
>
> Java, doxygen flavour, C# or what?
>
> Phobos has samples of all styles....
>
> Personally I don't like them all because they are mostly non readable in 
> source code,
> but, yes, they produce  more or less good results in generated docs.
> BTW: Do you know examples of useful generated docs?  (url will be 
> appreciated)
>
> I am going to use something extremely simple like:
>
> /**  show - Shows tooltip window
> - tt - ITooltip, reference to the implementation of ITooltip
>   interface - source of tooltip text.
> - screenPos - point, screen relative coordinates of the
>   origin of the tooltip window.
> = true - if window was shown, false - otherwise
> **/
> bool show(ITooltip tt, point screenPos) { ... }
>
> this is human readable (I guess ) and could be used as a source of 
> generated doc.
>
> Any ideas?
>
> ==============================================
> Seems like D *will* have a declarative UI (whatever it means) ahead of 
> time:
> I've almost finished with "springs" (vertical and horizontal)
> See: http://terrainformatica.com/screenshots/harmonia1.png
> And: http://terrainformatica.com/screenshots/HarmoniaDemo.zip
>
> Andrew.
>
May 04, 2005
Re: Preferred style of comments in source code.
On Wed, 4 May 2005 13:43:29 -0700, Andrew Fedoniouk wrote:

> What was last consensus, gentlemen?
> 
> Java, doxygen flavour, C# or what?
> 
> Phobos has samples of all styles....
> 
> Personally I don't like them all because they are mostly non readable in 
> source code,
> but, yes, they produce  more or less good results in generated docs.
> BTW: Do you know examples of useful generated docs?  (url will be 
> appreciated)
> 
> I am going to use something extremely simple like:
> 
> /**  show - Shows tooltip window
>  - tt - ITooltip, reference to the implementation of ITooltip
>    interface - source of tooltip text.
>  - screenPos - point, screen relative coordinates of the
>    origin of the tooltip window.
>  = true - if window was shown, false - otherwise
>  **/
> bool show(ITooltip tt, point screenPos) { ... }
> 
> this is human readable (I guess ) and could be used as a source of generated 
> doc.
> 
> Any ideas?

I've used a system of embedding documentation in source code for a few
years now that is based on a simple markup language. The documentation is
extracted from the source code and a set of HTML files is generated. You
can see the source code of 'build.d' from the download for a bigger example
but here is a smaller example ...

/* ============= The User Manual ======================================
__ /topic Introduction
__ /info
__ This is a utility to build an application using the D programming
__ language.
__ It does this by examining the source file supplied on the command line
__ to work out its dependant files, and then determines which need to be
__  compiled and which need to be linked to create the executable.
__
__ Alternatively, it can be used to create a Library file rather than an
__  executable.
__
__ The aim of the utility is to help remove the need for /i make files
__  or similar devices.

__ /topic Pragma
__ /info
__ The /b build utility supports the use of various pragma statements.
__ A pragma is a special statement embedded in the source code that
__  provides information to tools reading the source code.
__
__ They take the forms ...
__ /code
__       /b"pragma(" ~<name~> /b");"
__       /b"pragma(" ~<name~> /b"," ~<option~> [ /b","~<option~>] /b");"
__ /endcode
__
__ If the D compiler doesn't recognise the pragma, it will fail. So to
__  'hide' them from the compiler, you need to wrap them in a /b version
__  block. All the pragmas used by this utility need to be enclosed in
__  a /i build version.
__
__ Example:
__ /code
__       version(build) { pragma(nolink); }
__ /endcode

*/

This example doesn't show many of the neat features of the SML, but the
advantages for me is that it is simple to use, simple to remember, removes
the concern about layout, and you can write the documentation near the code
it relates to and it all gets pulled together during the generation
process. The generated HTML is simple and not distracting.

 http://svn.dsource.org/svn/projects/build/trunk/Docs/index.htm

The generator is a Euphoria program, but I'm currently porting it to D. And
BTW, that is a very simple thing to do and it has already found a couple of
old bugs.

-- 
Derek Parnell
Melbourne, Australia
http://www.dsource.org/projects/build v2.06 is now available. 04/May/2005
5/05/2005 7:05:01 AM
May 04, 2005
Re: Preferred style of comments in source code.
On Wed, 4 May 2005 13:43:29 -0700, Andrew Fedoniouk wrote:


Another example of the generated docs using the system I mentioned can be
found at ...

 http://www.users.bigpond.com/ddparnell/Euphoria/Docs/index.htm

This is the documentation for the Windows toolkit that I will be porting to
D one day.

-- 
Derek Parnell
Melbourne, Australia
http://www.dsource.org/projects/build v2.06 is now available. 04/May/2005
5/05/2005 7:12:56 AM
May 04, 2005
Re: Preferred style of comments in source code.
>
> I might have missed this in the forums:  is harmonia available on Linux as 
> well?
>

Not yet but it will be available on Linux too if somebody will
agree to help me in this. My Linux GUI programming experience is
more theoretical than practical.
As Harmonia is not using OS input widgets (only top level window frames)
then it is possible to build Harmonia/Linux in the window manager agnostic
fashion - directly on top of XWindow. (My guess)
Moreover Harmonia by itself can be used as a window manager or more
precise - window manager could be built using Harmonia.

Andrew.
May 04, 2005
Re: Preferred style of comments in source code.
Thanks for the link.
Indeed looks nice. It is a plus.
No D support. It is a minus. Striking out :)

Andrew.


"Pablo Aguilar" <paguilarg@hotmail.com> wrote in message 
news:d5bd9s$2q9v$1@digitaldaemon.com...
> Did you see Charlie's recent post about natural docs (www.naturaldocs.org) 
> ?
> Here's a sample on how to document: 
> http://www.naturaldocs.org/documenting.html
>
> Seems pretty readable, doesn't it?
> The downside is, there's no current support for D...
>
>
> Pablo
>
> "Andrew Fedoniouk" <news@terrainformatica.com> wrote in message 
> news:d5bc5i$2pd6$1@digitaldaemon.com...
>> What was last consensus, gentlemen?
>>
>> Java, doxygen flavour, C# or what?
>>
>> Phobos has samples of all styles....
>>
>> Personally I don't like them all because they are mostly non readable in 
>> source code,
>> but, yes, they produce  more or less good results in generated docs.
>> BTW: Do you know examples of useful generated docs?  (url will be 
>> appreciated)
>>
>> I am going to use something extremely simple like:
>>
>> /**  show - Shows tooltip window
>> - tt - ITooltip, reference to the implementation of ITooltip
>>   interface - source of tooltip text.
>> - screenPos - point, screen relative coordinates of the
>>   origin of the tooltip window.
>> = true - if window was shown, false - otherwise
>> **/
>> bool show(ITooltip tt, point screenPos) { ... }
>>
>> this is human readable (I guess ) and could be used as a source of 
>> generated doc.
>>
>> Any ideas?
>>
>> ==============================================
>> Seems like D *will* have a declarative UI (whatever it means) ahead of 
>> time:
>> I've almost finished with "springs" (vertical and horizontal)
>> See: http://terrainformatica.com/screenshots/harmonia1.png
>> And: http://terrainformatica.com/screenshots/HarmoniaDemo.zip
>>
>> Andrew.
>>
>
>
May 04, 2005
Re: Preferred style of comments in source code.
Thanks a lot, Derek,

Yes it close but the style I would like to avoid is:

__ They take the forms ...
__ /code
__       /b"pragma(" ~<name~> /b");"
__       /b"pragma(" ~<name~> /b"," ~<option~> [ /b","~<option~>] /b");"
__ /endcode

For me (probably only for me) it is hard to read something like this:
   /b"pragma(" ~<name~> /b");"
.....

The more I am looking on this the more coming to the conclusion
that documentation and source code should be separated.
But where to get time for such docs? :(

Andrew.


"Derek Parnell" <derek@psych.ward> wrote in message 
news:6xes2p79xu69$.16cxjkqk2ffic$.dlg@40tude.net...
> On Wed, 4 May 2005 13:43:29 -0700, Andrew Fedoniouk wrote:
>
>> What was last consensus, gentlemen?
>>
>> Java, doxygen flavour, C# or what?
>>
>> Phobos has samples of all styles....
>>
>> Personally I don't like them all because they are mostly non readable in
>> source code,
>> but, yes, they produce  more or less good results in generated docs.
>> BTW: Do you know examples of useful generated docs?  (url will be
>> appreciated)
>>
>> I am going to use something extremely simple like:
>>
>> /**  show - Shows tooltip window
>>  - tt - ITooltip, reference to the implementation of ITooltip
>>    interface - source of tooltip text.
>>  - screenPos - point, screen relative coordinates of the
>>    origin of the tooltip window.
>>  = true - if window was shown, false - otherwise
>>  **/
>> bool show(ITooltip tt, point screenPos) { ... }
>>
>> this is human readable (I guess ) and could be used as a source of 
>> generated
>> doc.
>>
>> Any ideas?
>
> I've used a system of embedding documentation in source code for a few
> years now that is based on a simple markup language. The documentation is
> extracted from the source code and a set of HTML files is generated. You
> can see the source code of 'build.d' from the download for a bigger 
> example
> but here is a smaller example ...
>
> /* ============= The User Manual ======================================
> __ /topic Introduction
> __ /info
> __ This is a utility to build an application using the D programming
> __ language.
> __ It does this by examining the source file supplied on the command line
> __ to work out its dependant files, and then determines which need to be
> __  compiled and which need to be linked to create the executable.
> __
> __ Alternatively, it can be used to create a Library file rather than an
> __  executable.
> __
> __ The aim of the utility is to help remove the need for /i make files
> __  or similar devices.
>
> __ /topic Pragma
> __ /info
> __ The /b build utility supports the use of various pragma statements.
> __ A pragma is a special statement embedded in the source code that
> __  provides information to tools reading the source code.
> __
> __ They take the forms ...
> __ /code
> __       /b"pragma(" ~<name~> /b");"
> __       /b"pragma(" ~<name~> /b"," ~<option~> [ /b","~<option~>] /b");"
> __ /endcode
> __
> __ If the D compiler doesn't recognise the pragma, it will fail. So to
> __  'hide' them from the compiler, you need to wrap them in a /b version
> __  block. All the pragmas used by this utility need to be enclosed in
> __  a /i build version.
> __
> __ Example:
> __ /code
> __       version(build) { pragma(nolink); }
> __ /endcode
>
> */
>
> This example doesn't show many of the neat features of the SML, but the
> advantages for me is that it is simple to use, simple to remember, removes
> the concern about layout, and you can write the documentation near the 
> code
> it relates to and it all gets pulled together during the generation
> process. The generated HTML is simple and not distracting.
>
>  http://svn.dsource.org/svn/projects/build/trunk/Docs/index.htm
>
> The generator is a Euphoria program, but I'm currently porting it to D. 
> And
> BTW, that is a very simple thing to do and it has already found a couple 
> of
> old bugs.
>
> -- 
> Derek Parnell
> Melbourne, Australia
> http://www.dsource.org/projects/build v2.06 is now available. 04/May/2005
> 5/05/2005 7:05:01 AM
May 04, 2005
Re: Preferred style of comments in source code.
Andrew Fedoniouk wrote:
> What was last consensus, gentlemen?
> 
> Java, doxygen flavour, C# or what?
> 
> Phobos has samples of all styles....
> 
> Personally I don't like them all ...

I really don't care what type of documentation is used, but it seems 
like there should be a standard. And it seems like that standard should 
be something like the D Style Guide, authored and maintained by Digital 
Mars. (Though I don't think many people actually pay much attention to 
the D style guide, preferring instead to stick with their old code 
formatting & variable naming habits from c++, java, perl, vb, or whatever.)

--Benji
May 04, 2005
Re: Preferred style of comments in source code.
Andrew Fedoniouk wrote:
>>I might have missed this in the forums:  is harmonia available on Linux as 
>>well?
>>
> 
> 
> Not yet but it will be available on Linux too if somebody will
> agree to help me in this. My Linux GUI programming experience is
> more theoretical than practical.
> As Harmonia is not using OS input widgets (only top level window frames)
> then it is possible to build Harmonia/Linux in the window manager agnostic
> fashion - directly on top of XWindow. (My guess)
> Moreover Harmonia by itself can be used as a window manager or more
> precise - window manager could be built using Harmonia.
> 
> Andrew.
> 

I see.  So I guess one could also build Harmonia on top of an OpenGL 
surface as well, if need be?

My XWindow programming skills are practically nil, but I wouldn't mind 
fooling around with some Linux GUI integration; I've basically only 
mildly familiar with working with GTK and OpenGL on both platforms; I 
realize GTK has no use here.  Is Harmonia going to be put on dsource at 
any time?

Thanks.  Harmonia is really quite pretty!

-JJR
« First   ‹ Prev
1 2 3
Top | Discussion index | About this forum | D home