Should DDoc list all publics by default?

torhu fake at address.dude
Fri Jul 6 07:41:41 PDT 2007


I find that I sometimes do things like this in order to get dmd to 
include a definition in the doc output:

///
struct Point
{
     int x;  ///
     int y;  ///
}


This doesn't look that great.  Adding actual comments to something like 
this feels a bit silly:

/// A point.
struct Point
{
     int x;  /// X coordinate.
     int y;  /// X coordinate.
}

The same problem applies to functions.  I try to write reasonably 
self-explanatory code, with descriptive function names.  It would be 
nice not having to add '///' to every single line function just to get 
them in the docs.  It makes the code look messy.

Reading the html docs is a good way to get an overview of your project 
as it's progressing.  So I guess part of the reason I want this behavior 
is that I want to see the API docs before I'm done adding proper doc 
comments to everything.  Maybe this isn't quite what the doc system is 
supposed to be used for, but still.

The suggestion is: Make dmd -D include all public declarations by 
default, even those with no doc comments.  Any opinions, counter 
examples, whatever?



More information about the Digitalmars-d mailing list