www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Documenting privates

reply Sean Kelly <sean f4.ca> writes:
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
Oct 21 2005
next sibling parent reply "Walter Bright" <newshound digitalmars.com> writes:
"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.
Oct 21 2005
next sibling parent reply Sean Kelly <sean f4.ca> writes:
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
Oct 21 2005
parent pragma <pragma_member pathlink.com> writes:
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
Oct 21 2005
prev sibling parent reply Derek Parnell <derek psych.ward> writes:
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
Oct 21 2005
next sibling parent Sean Kelly <sean f4.ca> writes:
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
Oct 21 2005
prev sibling next sibling parent "Kris" <fu bar.com> writes:
"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?
Oct 21 2005
prev sibling parent reply "Walter Bright" <newshound digitalmars.com> writes:
"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.
Oct 21 2005
next sibling parent Derek Parnell <derek psych.ward> writes:
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
Oct 21 2005
prev sibling parent reply Sean Kelly <sean f4.ca> writes:
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
Oct 21 2005
parent "Walter Bright" <newshound digitalmars.com> writes:
"Sean Kelly" <sean f4.ca> wrote in message
news:djcar1$bnm$1 digitaldaemon.com...

 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?


I understand what you're trying to achieve, but I think Ddoc is not the
right tool for that. I think the tool that fits that purpose is a good code
editor that is aware that it is D code and can parse it, extract
information, etc., and present it to the coder. Ddoc output is meant for the
user of the module, not the maintainer of it. Nobody expects Ddoc to
document function local variables, because they have no meaning outside of
the function. I think the analogy to private members is accurate.

The user of the module shouldn't be presented with internal implementation
details, which is what private members represent. You're right, Ddoc does
impose a certain structure and discipline on the result, and that's one
aspect of it <g>.

BTW, nothing stops you from attaching documentation comments to private
members, local variables, etc. A D-aware code editor could certainly make
use of them. Take a look at how the D syntax highlighter works, it takes
advantage of the lexer to do all the hard stuff for it, making the
highlighter trivial. A syntax directed code editor could do something
analogous by latching on to the parser.
Oct 21 2005
prev sibling parent reply J C Calvarese <technocrat7 gmail.com> writes:
In article <djbafb$2e24$1 digitaldaemon.com>, Sean Kelly says...

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() { ... } }


This seemed to work for me:

// begin code

version(testVersion)
{
public: 
}
else
{
private:
}

extern(C) void func() {return;} /// Some function

// end code

And I compiled it like this:
dmd priv_test.d -D -c -o- -version=testVersion

I don't know why your version didn't work.

jcc7
Oct 24 2005
parent Sean Kelly <sean f4.ca> writes:
In article <djj1ir$1413$1 digitaldaemon.com>, J C Calvarese says...

In article <djbafb$2e24$1 digitaldaemon.com>, Sean Kelly says...

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() { ... } }


This seemed to work for me:

// begin code

version(testVersion)
{
public: 
}
else
{
private:
}

extern(C) void func() {return;} /// Some function

// end code

And I compiled it like this:
dmd priv_test.d -D -c -o- -version=testVersion

I don't know why your version didn't work.


It turns out I had some pre "-o-" artifacts in my makefile that were screwing
things up.  Once I removed them everything worked as expected.


Sean

jcc7
Oct 24 2005