Should DDoc list all publics by default?

[Derek Parnell]

On Fri, 06 Jul 2007 11:11:18 -0700, BCS wrote:

> torhu wrote:
>> 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?
> 
> What I want is a way to get /private/ stuff to show up in ddoc!

Absolutely YES! Some documentation is meant for 'internal' use within the
organisation that owns the (closed) source code.

-- 
Derek Parnell
Melbourne, Australia
skype: derek.j.parnell