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

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

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