www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Preferred style of comments in source code.

reply "Andrew Fedoniouk" <news terrainformatica.com> writes:
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
next sibling parent reply John Reimer <brk_6502 yahoo.com> writes:
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
parent reply "Andrew Fedoniouk" <news terrainformatica.com> writes:
 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
parent reply John Reimer <brk_6502 yahoo.com> writes:
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
May 04 2005
parent reply "Andrew Fedoniouk" <news terrainformatica.com> writes:
 I see.  So I guess one could also build Harmonia on top of an OpenGL 
 surface as well, if need be?

Yes. There is only one Graphics object which handles all drawings in Harmonia. If you will implement its methods for OpenGL it will work on OpenGL: Graphics class is here (undocumented so far): http://terrainformatica.com/screenshots/graphics.d There are two more files in gx package http://terrainformatica.com/screenshots/geometry.d http://terrainformatica.com/screenshots/images.d but they are directly unrelated to the rendering process.
 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?

As I've mentioned before it is already available on our SVN server. No anonymous access so far though.
 Harmonia is really quite pretty!

Thanks.
May 04 2005
parent John Reimer <brk_6502 yahoo.com> writes:
On Wed, 04 May 2005 15:57:42 -0700, Andrew Fedoniouk wrote:

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

Yes. There is only one Graphics object which handles all drawings in Harmonia. If you will implement its methods for OpenGL it will work on OpenGL: Graphics class is here (undocumented so far): http://terrainformatica.com/screenshots/graphics.d There are two more files in gx package http://terrainformatica.com/screenshots/geometry.d http://terrainformatica.com/screenshots/images.d but they are directly unrelated to the rendering process.

Great, thanks.
 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?

As I've mentioned before it is already available on our SVN server. No anonymous access so far though.

Ah... you probably have mentioned it before. I'll have a look at your svn server then. -JJR
May 04 2005
prev sibling next sibling parent reply "Pablo Aguilar" <paguilarg hotmail.com> writes:
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
parent reply "Andrew Fedoniouk" <news terrainformatica.com> writes:
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
parent reply Derek Parnell <derek psych.ward> writes:
On Wed, 4 May 2005 14:47:24 -0700, Andrew Fedoniouk wrote:

 Thanks for the link.

 http://www.naturaldocs.org/documenting.html


 Indeed looks nice. It is a plus.
 No D support. It is a minus. Striking out :)

Wow! This is *so* close to what I'm doing that I might just be able to implement a lot of this in my MakeDoc utility. -- Derek Melbourne, Australia 5/05/2005 9:03:56 AM
May 04 2005
parent reply "Andrew Fedoniouk" <news terrainformatica.com> writes:
Derek, and how far this *so* is close to it?

I have some time today to start writing docs.... :)

Andrew


"Derek Parnell" <derek psych.ward> wrote in message 
news:owbprp404kz0.125ty6odtthz9.dlg 40tude.net...
 On Wed, 4 May 2005 14:47:24 -0700, Andrew Fedoniouk wrote:

 Thanks for the link.

 http://www.naturaldocs.org/documenting.html


 Indeed looks nice. It is a plus.
 No D support. It is a minus. Striking out :)

Wow! This is *so* close to what I'm doing that I might just be able to implement a lot of this in my MakeDoc utility. -- Derek Melbourne, Australia 5/05/2005 9:03:56 AM

May 04 2005
parent reply Derek Parnell <derek psych.ward> writes:
On Wed, 4 May 2005 16:22:01 -0700, Andrew Fedoniouk wrote:

 Derek, and how far this *so* is close to it?

Hard to quantify. I need some time to inspect it a bit more. The thing that immediately causes me to hesitate is that it seems to want to know about the syntax of the language the program is coded in. I am trying to avoid that. There maybe a compromise though.
 I have some time today to start writing docs.... :)

Then start writing! I'd stick to plain text until you decide on which 'markup' style to use. I'm still a few days away from finishing my port of MakeDoc to D, and when that's completed I can look at incorporating some of the ideas from the 'Natural' guys. -- Derek Melbourne, Australia 5/05/2005 9:27:49 AM
May 04 2005
parent reply "Andrew Fedoniouk" <news terrainformatica.com> writes:
 Then start writing! I'd stick to plain text until....

Plain text!? No way! I've recalled that I have nice html wysiwyg editor :)) The fastest editor in the block, btw, :-P Here is the first bird: http://www.terrainformatica.com/harmonia/map.htm (btw. I don't know how people are doing html tables without wysiwyg...) Andrew. "Derek Parnell" <derek psych.ward> wrote in message news:14bv0u5bbdzvy$.1njq6ruyaxj9n$.dlg 40tude.net...
 On Wed, 4 May 2005 16:22:01 -0700, Andrew Fedoniouk wrote:

 Derek, and how far this *so* is close to it?

Hard to quantify. I need some time to inspect it a bit more. The thing that immediately causes me to hesitate is that it seems to want to know about the syntax of the language the program is coded in. I am trying to avoid that. There maybe a compromise though.
 I have some time today to start writing docs.... :)

Then start writing! I'd stick to plain text until you decide on which 'markup' style to use. I'm still a few days away from finishing my port of MakeDoc to D, and when that's completed I can look at incorporating some of the ideas from the 'Natural' guys. -- Derek Melbourne, Australia 5/05/2005 9:27:49 AM

May 04 2005
next sibling parent reply Derek Parnell <derek psych.ward> writes:
On Wed, 4 May 2005 23:25:55 -0700, Andrew Fedoniouk wrote:

 Then start writing! I'd stick to plain text until....

Plain text!? No way! I've recalled that I have nice html wysiwyg editor :)) The fastest editor in the block, btw, :-P

LOL... I looked at BlockNote site just now and thought, hmmm... I've seen this style of GUI before ... then I saw the " Andrew Fedoniouk. Author of the BlockNote." Nice product.
 Here is the first bird:
 http://www.terrainformatica.com/harmonia/map.htm

I think I know which GUI engine I'll be porting my windowing library to ;-)
 (btw. I don't know how people are doing html tables without wysiwyg...)

Huh? What's a html table ;-) -- Derek Parnell Melbourne, Australia http://www.dsource.org/projects/build/ v2.06 released 04/May/2005 http://www.prowiki.org/wiki4d/wiki.cgi?FrontPage 5/05/2005 4:46:06 PM
May 04 2005
parent "Andrew Fedoniouk" <news terrainformatica.com> writes:
 I've recalled that I have nice html wysiwyg editor :))
 The fastest editor in the block, btw, :-P

LOL... I looked at BlockNote site just now and thought, hmmm... I've seen this style of GUI before ... then I saw the " Andrew Fedoniouk. Author of the BlockNote." Nice product.

Thanks, Derek. David Glazman in his NVU (http://nvu.com/tree.jpg) is also using this layout and GUI style. He is even trying to reproduce BlockNote's rulers (http://blocknote.net/info/rulersexplained.htm) But his is sticked with Gecko engine ;-) Andrew.
May 05 2005
prev sibling parent "Unknown W. Brackets" <unknown simplemachines.org> writes:
Yuck.  I don't know how people can stand to use a wysiwywyg editor.

-[Unknown]


 (btw. I don't know how people are doing html tables without wysiwyg...)

May 05 2005
prev sibling next sibling parent reply Derek Parnell <derek psych.ward> writes:
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
parent reply "Andrew Fedoniouk" <news terrainformatica.com> writes:
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
parent Derek Parnell <derek psych.ward> writes:
On Wed, 4 May 2005 14:54:33 -0700, Andrew Fedoniouk wrote:

 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");"
 .....

LOL ... Yes that is a bit obtuse. That was a 'special' case in which I wanted to bold certain delimiter characters, and I chose to use '<' which can get Browsers confused. I could have simply coded it as ...
 They take the forms ...
 /code
       pragma( name );
       pragma( name, option [, option] );
 /endcode

 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? :(

That is exactly why docs and code should be in the same file. The better development strategy is to write up the documentation then implement what you documented. If they are physically close to each other, it becomes easy to tweak either the docs or code as required, and keep them in sync. When they are in different files, the human tendency is to write code then, if time permits, update the docs. -- Derek Parnell Melbourne, Australia http://www.dsource.org/projects/build/ v2.06 released 04/May/2005 http://www.prowiki.org/wiki4d/wiki.cgi?FrontPage 5/05/2005 9:02:12 AM
May 04 2005
prev sibling next sibling parent Derek Parnell <derek psych.ward> writes:
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
prev sibling next sibling parent Benji Smith <dlanguage xxagg.com> writes:
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
prev sibling parent reply =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:
Andrew Fedoniouk wrote:

 What was last consensus, gentlemen?
 
 Java, doxygen flavour, C# or what?
 
 Phobos has samples of all styles....

Consensus ? You must be new around here :-) Seriously, I put up some minor comment examples of a JavaDoc/Doxygen based inline documentation style, at: http://www.prowiki.org/wiki4d/wiki.cgi?DocComments/DStyle I've used it for C/C++ projects (and for a lot of Java...), and it has worked out good. Minimal "boilerplate" to write. Doxygen still has a few issues with any "complicated" D constructs, but it's working OK for the simple stuff - especially with dfilter. See http://www.prowiki.org/wiki4d/wiki.cgi?DoxygenIssues Dmitri is accepting bug reports for Doxygen and the D language, especially if they come with patches and source code to fix them... --anders
May 05 2005
parent reply "Andrew Fedoniouk" <news terrainformatica.com> writes:
 Consensus ? You must be new around here :-)

Is it really so bad ?:) Thanks for links, Anders.
May 05 2005
parent =?ISO-8859-1?Q?Anders_F_Bj=F6rklund?= <afb algonet.se> writes:
Andrew Fedoniouk wrote:

Consensus ? You must be new around here :-)

Is it really so bad ?:)

Bad and bad... Let's just say it's definitely not boring. ;-) And while most of it comes from people with different ideas and opinions on how things "should be done", a fact is that D (just like C++) *encourages* multi-paradigm programming... And that tends to rub off on other things too. Like comments. But I think "majority" is more likely to have, than "consensus" ? And sometimes even majority on for instance this newsgroup doesn't have much effect, since D is not being decided by eg. a committee. For better, and for worse. (at least it's a horse, and not a camel) Anyway, I gave my opionionated suggestion. "JavaDoc", more or less. --anders
May 06 2005