www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Should DDoc list all publics by default?

reply torhu <fake address.dude> writes:
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?
Jul 06 2007
next sibling parent reply Lutger <lutger.blijdestijn gmail.com> writes:
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.
Jul 06 2007
parent "Stewart Gordon" <smjg_1998 yahoo.com> writes:
"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.
Jul 08 2007
prev sibling next sibling parent Frits van Bommel <fvbommel REMwOVExCAPSs.nl> writes:
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.
Jul 06 2007
prev sibling next sibling parent reply "Chris Miller" <chris dprogramming.com> writes:
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
Jul 06 2007
parent Charles D Hixson <charleshixsn earthlink.net> writes:
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.
Jul 12 2007
prev sibling parent reply BCS <BCS pathlink.com> writes:
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!
Jul 06 2007
parent Derek Parnell <derek psych.ward> writes:
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
Jul 06 2007