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