• Sean Kelly <sean f4.ca> Oct 21 2005
• "Walter Bright" <newshound digitalmars.com> Oct 21 2005
• Sean Kelly <sean f4.ca> Oct 21 2005
• pragma <pragma_member pathlink.com> Oct 21 2005
• Derek Parnell <derek psych.ward> Oct 21 2005
• Sean Kelly <sean f4.ca> Oct 21 2005
• "Kris" <fu bar.com> Oct 21 2005
• "Walter Bright" <newshound digitalmars.com> Oct 21 2005
• Derek Parnell <derek psych.ward> Oct 21 2005
• Sean Kelly <sean f4.ca> Oct 21 2005
• "Walter Bright" <newshound digitalmars.com> Oct 21 2005
• J C Calvarese <technocrat7 gmail.com> Oct 24 2005
• Sean Kelly <sean f4.ca> Oct 24 2005

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

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

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

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

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

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

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

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

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

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

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

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

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