I have a bunch of private extern(C) functions I'd like to generate documentation for and I've been unable to accomplish this so far.  Simply adding DDoc comments to the functions doesn't work, so I tried this:

version(DDoc) { /** blah blah */ extern(C) void func() {} }
else private { extern(C) void func() { ... } }

and added -version=DDoc to the command-line call, but I still didn't see the comments.  I can live with DDoc not generating documentation for private data, but it would be nice to have some sort of workaround for the few instances where this may be desired behavior.  Does anyone have any suggestions for how I might accomplish this?


Sean

"Sean Kelly" <sean@f4.ca> wrote in message news:djbafb$2e24$1@digitaldaemon.com...
> I have a bunch of private extern(C) functions I'd like to generate
documentation
> for and I've been unable to accomplish this so far.  Simply adding DDoc
comments
> to the functions doesn't work, so I tried this:
>
> version(DDoc) { /** blah blah */ extern(C) void func() {} }
> else private { extern(C) void func() { ... } }
>
> and added -version=DDoc to the command-line call, but I still didn't see
the
> comments.  I can live with DDoc not generating documentation for private
data,
> but it would be nice to have some sort of workaround for the few instances
where
> this may be desired behavior.  Does anyone have any suggestions for how I
might
> accomplish this?

The idea is that private stuff is only for the implementor of the class, not for anyone else, so Ddoc should not generate public documentation for it.

In article <djbea9$2hgu$1@digitaldaemon.com>, Walter Bright says...
>
>"Sean Kelly" <sean@f4.ca> wrote in message news:djbafb$2e24$1@digitaldaemon.com...
>> I have a bunch of private extern(C) functions I'd like to generate
>documentation
>> for and I've been unable to accomplish this so far.  Simply adding DDoc
>comments
>> to the functions doesn't work, so I tried this:
>>
>> version(DDoc) { /** blah blah */ extern(C) void func() {} }
>> else private { extern(C) void func() { ... } }
>>
>> and added -version=DDoc to the command-line call, but I still didn't see
>the
>> comments.  I can live with DDoc not generating documentation for private
>data,
>> but it would be nice to have some sort of workaround for the few instances
>where
>> this may be desired behavior.  Does anyone have any suggestions for how I
>might
>> accomplish this?
>
>The idea is that private stuff is only for the implementor of the class, not for anyone else, so Ddoc should not generate public documentation for it.

I agree, however I'm in the awkward position of trying to document a library which has requirements for certain non-public functionality.  Rather than write that separately, it would be nice if there were some way to use DDoc.  I'm quite open to doing nasty things with static if, version blocks, etc, just so long as I can keep the private stuff private in release builds.  In C, it would be simple enough to elide the 'private' label when generating documentation, but I'm not sure how to accomplish this in D.


Sean

In article <djbfuq$2ive$1@digitaldaemon.com>, Sean Kelly says...
>
>In article <djbea9$2hgu$1@digitaldaemon.com>, Walter Bright says...
>>
>>"Sean Kelly" <sean@f4.ca> wrote in message news:djbafb$2e24$1@digitaldaemon.com...
>>> I have a bunch of private extern(C) functions I'd like to generate
>>documentation
>>> for and I've been unable to accomplish this so far.  Simply adding DDoc
>>comments
>>> to the functions doesn't work, so I tried this:
>>>
>>> version(DDoc) { /** blah blah */ extern(C) void func() {} }
>>> else private { extern(C) void func() { ... } }
>>>
>>> and added -version=DDoc to the command-line call, but I still didn't see
>>the
>>> comments.  I can live with DDoc not generating documentation for private
>>data,
>>> but it would be nice to have some sort of workaround for the few instances
>>where
>>> this may be desired behavior.  Does anyone have any suggestions for how I
>>might
>>> accomplish this?
>>
>>The idea is that private stuff is only for the implementor of the class, not for anyone else, so Ddoc should not generate public documentation for it.
>
>I agree, however I'm in the awkward position of trying to document a library which has requirements for certain non-public functionality.  Rather than write that separately, it would be nice if there were some way to use DDoc.  I'm quite open to doing nasty things with static if, version blocks, etc, just so long as I can keep the private stuff private in release builds.  In C, it would be simple enough to elide the 'private' label when generating documentation, but I'm not sure how to accomplish this in D.
>

Would using 'protected' or 'package' help instead of 'private'?  I think D allows those at the module level, if I'm not mistaken.

protected extern(C) void func();

- EricAnderton at yahoo

On Fri, 21 Oct 2005 11:59:20 -0700, Walter Bright wrote:

> "Sean Kelly" <sean@f4.ca> wrote in message news:djbafb$2e24$1@digitaldaemon.com...
>> I have a bunch of private extern(C) functions I'd like to generate
> documentation
>> for and I've been unable to accomplish this so far.  Simply adding DDoc
> comments
>> to the functions doesn't work, so I tried this:
>>
>> version(DDoc) { /** blah blah */ extern(C) void func() {} }
>> else private { extern(C) void func() { ... } }
>>
>> and added -version=DDoc to the command-line call, but I still didn't see
> the
>> comments.  I can live with DDoc not generating documentation for private
> data,
>> but it would be nice to have some sort of workaround for the few instances
> where
>> this may be desired behavior.  Does anyone have any suggestions for how I
> might
>> accomplish this?
> 
> The idea is that private stuff is only for the implementor of the class, not for anyone else, so Ddoc should not generate public documentation for it.

Why assume that all documentation is 'public'. My company documents our code for internal usage only as the products we produce are not open-source. By documenting 'private' sections we educate new coders etc.. about the internal workings of the code.

-- 
Derek Parnell
Melbourne, Australia
22/10/2005 7:34:11 AM

In article <12b4gw63ku61w$.wa6w2febyh83$.dlg@40tude.net>, Derek Parnell says...
>
>Why assume that all documentation is 'public'. My company documents our code for internal usage only as the products we produce are not open-source. By documenting 'private' sections we educate new coders etc.. about the internal workings of the code.

Exactly.  In fact, the ideal solution might be to have an option to generate different versions of documentation targeted at different parties.  Private stuff could be maintained for internal use, but the public portions could be generated separately for release to clients.


Sean

"Derek Parnell" <derek@psych.ward> wrote...
> Why assume that all documentation is 'public'. My company documents our code for internal usage only as the products we produce are not open-source. By documenting 'private' sections we educate new coders etc.. about the internal workings of the code.

Right on.

This 'feature' would be useful for open-source also. I mean, I'd like to document the 'private' sections of Mango for the same reasons. As Sean implies, perhaps there should be a '-verbose' option to emit such things?

"Derek Parnell" <derek@psych.ward> wrote in message news:12b4gw63ku61w$.wa6w2febyh83$.dlg@40tude.net...
> > The idea is that private stuff is only for the implementor of the class,
not
> > for anyone else, so Ddoc should not generate public documentation for
it.
>
> Why assume that all documentation is 'public'. My company documents our code for internal usage only as the products we produce are not open-source. By documenting 'private' sections we educate new coders etc.. about the internal workings of the code.

I didn't mean public in terms of the general public, but in terms of the user of the class not being its implementor. Ordinary comments are for documenting internal workings of the code, I don't think that's the place for generated documentation. Private variables are like local variables inside a function, the documentation for them is not meant to be exposed to the user of the class/function.

On Fri, 21 Oct 2005 16:37:47 -0700, Walter Bright wrote:

> "Derek Parnell" <derek@psych.ward> wrote in message news:12b4gw63ku61w$.wa6w2febyh83$.dlg@40tude.net...
>>> The idea is that private stuff is only for the implementor of the class,
> not
>>> for anyone else, so Ddoc should not generate public documentation for
> it.
>>
>> Why assume that all documentation is 'public'. My company documents our code for internal usage only as the products we produce are not open-source. By documenting 'private' sections we educate new coders etc.. about the internal workings of the code.
> 
> I didn't mean public in terms of the general public, but in terms of the user of the class not being its implementor. Ordinary comments are for documenting internal workings of the code, I don't think that's the place for generated documentation.

I understand exactly what you are saying. My point of difference is about the way that such private documentation is made accessible to the people who need it. True, it could be *only* in the source code comments, just like the 'non-public' comments/documentation. However, it is often better presented as a part of the program's entire documentation manual. One immediate benefit is that it can be used by people while they do not have access to the source code at the time. Private code documentation also benefits from the DDoc formatting that comments don't have. Further more, DDoc is able to generate useful documentation from the code itself, and that would benefit coders, and their managers, too.

> Private variables are like local variables
> inside a function, the documentation for them is not meant to be exposed to
> the user of the class/function.

Who is 'the user'? In one context, it is the people needed to *maintain* the source code, and anything to help them is a benefit.

-- 
Derek Parnell
Melbourne, Australia
22/10/2005 10:14:40 AM

In article <djbujk$4d$2@digitaldaemon.com>, Walter Bright says...
>
>I didn't mean public in terms of the general public, but in terms of the user of the class not being its implementor. Ordinary comments are for documenting internal workings of the code, I don't think that's the place for generated documentation. Private variables are like local variables inside a function, the documentation for them is not meant to be exposed to the user of the class/function.

But they can be useful for a maintainer.  At the very least, DDoc would impose a degree of structure on documentation for code that is typically poorly documented if it is documented at all.  It may also serve to encourage programmers to think a bit more about how their classes are implemented if there is an official way to document it at that level.  I also occasionally find myself wishing I had a concise reference for the implementation of code when I'm trying to make sense of what a function does.  Sure, I could open up all the source files being referenced, but I could do the same for public functions.  I do understand why DDoc ignores private blocks now, but to some degree this feels like an arbitrary limitation.  If I want to document every nook and cranny of my code--if only for my own personal use--why shouldn't I be able to?


Sean