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

 for and I've been unable to accomplish this so far.  Simply adding DDoc

 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

 comments.  I can live with DDoc not generating documentation for private

 but it would be nice to have some sort of workaround for the few instances

 this may be desired behavior.  Does anyone have any suggestions for how I

 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

 for and I've been unable to accomplish this so far.  Simply adding DDoc

 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

 comments.  I can live with DDoc not generating documentation for private

 but it would be nice to have some sort of workaround for the few instances

 this may be desired behavior.  Does anyone have any suggestions for how I

 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

 for and I've been unable to accomplish this so far.  Simply adding DDoc

 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

 comments.  I can live with DDoc not generating documentation for private

 but it would be nice to have some sort of workaround for the few instances

 this may be desired behavior.  Does anyone have any suggestions for how I

 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

 for and I've been unable to accomplish this so far.  Simply adding DDoc

 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

 comments.  I can live with DDoc not generating documentation for private

 but it would be nice to have some sort of workaround for the few instances

 this may be desired behavior.  Does anyone have any suggestions for how I

 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,


 for anyone else, so Ddoc should not generate public documentation for


 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,


 for anyone else, so Ddoc should not generate public documentation for


 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


the user of the class/function.

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

 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

 trying to make sense of what a function does.  Sure, I could open up all

 source files being referenced, but I could do the same for public

 do understand why DDoc ignores private blocks now, but to some degree this

 like an arbitrary limitation.  If I want to document every nook and cranny

 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