View mode: basic / threaded / horizontal-split · Log in · Help
July 06, 2007
Should DDoc list all publics by default?
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?
July 06, 2007
Re: Should DDoc list all publics by default?
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.

Personally I don't mind these empty slashes. But documenting this with 
comments is silly indeed.

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

I think it is a good feature (although it could be done in other tools). 
It will also help to generate 'documentation' for projects that are not 
documented at all.

But I think it should not be done by default, instead a switch for this 
should be given. The main reason is that as you document your api for 
others, you want control over what not to include (even if they are 
public methods). That kind of control should be the default, so that 
when others generate documentation from your source they get it how you 
intended it to be.
July 06, 2007
Re: Should DDoc list all publics by default?
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;  ///
> }
> 
[snip]
> 
> The suggestion is: Make dmd -D include all public declarations by 
> default, even those with no doc comments.  Any opinions, counter 
> examples, whatever?

It would be very nice indeed to at least have this as an option (maybe 
even the default, with perhaps a switch to turn it off?).

I find it very annoying when reading for instance the Tango docs that I 
have to click the source link for some modules just because they didn't 
document every enum member. Including all publicly accessible symbols[1] 
in the doc by default would very much improve the readability there, IMHO.


[1]: That includes e.g. protected class members of non-final classes, 
not just those that are literally "public", by the way.
July 06, 2007
Re: Should DDoc list all publics by default?
I would very much want this. This way you can also see what you forgot to  
make non-public; you don't want people to depend on stuff you intended on  
being internal (which seems to happen quite often from Phobos).

Also, I'd like a way to specify "don't include in documentation" from the  
source. deprecated could be one way, and/or something like /// ddoc-exclude
July 06, 2007
Re: Should DDoc list all publics by default?
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!
July 06, 2007
Re: Should DDoc list all publics by default?
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
July 08, 2007
Re: Should DDoc list all publics by default?
"Lutger" <lutger.blijdestijn@gmail.com> wrote in message 
news:f6lnbn$11bv$1@digitalmars.com...
<snip>
> But I think it should not be done by default, instead a switch for this 
> should be given. The main reason is that as you document your api for 
> others, you want control over what not to include (even if they are public 
> methods). That kind of control should be the default, so that when others 
> generate documentation from your source they get it how you intended it to 
> be.

Doesn't quite follow.  Not doing anything doesn't in itself constitute 
exercising control.

By not documenting something, it strikes me as a more likely assumption that 
the coder hasn't got round to documenting it yet, rather than wants it to be 
hidden.

On this basis, there should be an explicit comment notation to tell DDoc not 
to document something.

Stewart.
July 12, 2007
Re: Should DDoc list all publics by default?
Chris Miller wrote:
> I would very much want this. This way you can also see what you forgot 
> to make non-public; you don't want people to depend on stuff you 
> intended on being internal (which seems to happen quite often from Phobos).
> 
> Also, I'd like a way to specify "don't include in documentation" from 
> the source. deprecated could be one way, and/or something like /// 
> ddoc-exclude
Not deprecated.  That means something specific and else.
///exclude
seems like a reasonable choice, or even
///--
Though that would chance conflicting with some people's lines 
of separation.  Perhaps
///No
would be better.  And if you wanted "No" as your documentation 
you could do
/// No

It would be a bit error prone, but short is important, and it 
shouldn't cause a problem very often.  (And then not a serious 
one.)  Still, perhaps
///NoPR
would be better.  Mnemonic, still fairly short.  Less chance 
for conflict.
Top | Discussion index | About this forum | D home