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;  ///
 }
 

 
 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

///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