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?

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.

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.

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

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!

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

"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. 

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.