View mode: basic / threaded / horizontal-split · Log in · Help
October 06, 2012
ddoc - documenting private variables
How does one generate documentation for private variables?  ...  Other, 
I mean, than switching to DOxygen (which has it's own problems with D).
October 06, 2012
Re: ddoc - documenting private variables
On Saturday, October 06, 2012 13:10:31 Charles Hixson wrote:
> How does one generate documentation for private variables?  ...  Other,
> I mean, than switching to DOxygen (which has it's own problems with D).

AFAIK, you can't. ddoc is configured primarily (entirely?) through the ddoc file 
that you use, and that's really for configuring how the information is 
displayed, not what is displayed.

ddoc is a nice, simple tool that allows you to easily generate documentation, 
and you can do some fairly powerful stuff through ddoc macros, but it's not 
designed to be anywhere near as flexible or powerful as doxygen.

- Jonathan M Davis
October 06, 2012
Re: ddoc - documenting private variables
On Saturday, 6 October 2012 at 20:34:47 UTC, Jonathan M Davis 
wrote:
> ddoc is a nice, simple tool that allows you to easily generate 
> documentation, and you can do some fairly powerful stuff 
> through ddoc macros, but it's not designed to be anywhere near 
> as flexible or powerful as doxygen.

 Hmm off hand I don't recall DDoc supporting BBCode, probably 
not. However, if it did and CSS included something for 
folding/hiding/highlighting portions, then that might make for an 
additional functionality.

 But that's just a thrown out idea.
October 07, 2012
Re: ddoc - documenting private variables
On 10/06/2012 01:22 PM, Jonathan M Davis wrote:
> On Saturday, October 06, 2012 13:10:31 Charles Hixson wrote:
>> How does one generate documentation for private variables?  ...  Other,
>> I mean, than switching to DOxygen (which has it's own problems with D).
>
> AFAIK, you can't. ddoc is configured primarily (entirely?) through the ddoc file
> that you use, and that's really for configuring how the information is
> displayed, not what is displayed.
>
> ddoc is a nice, simple tool that allows you to easily generate documentation,
> and you can do some fairly powerful stuff through ddoc macros, but it's not
> designed to be anywhere near as flexible or powerful as doxygen.
>
> - Jonathan M Davis

Well, DOxygen works ok if you don't use function contracts, and possibly 
if you keep the entire program in one file.  (It's been awhile since I 
used it with D, so I don't quite remember the limitations, and maybe 
they've improved it.)

One way in which I prefer DOxygen over ddoc is that the documentation 
comments are a bit more compact.  Since I only have one screen, that 
sometimes makes things a lot more legible.  OTOH, the last time I used 
it I certainly got annoyed by it's limitations (in dealing with D).  But 
this time I really need to document private variables, so I guess 
there's no choice (unless I go with something like robodoc...ugh).
October 07, 2012
Re: ddoc - documenting private variables
On Saturday, October 06, 2012 23:43:39 Charles Hixson wrote:
> Well, DOxygen works ok if you don't use function contracts, and possibly
> if you keep the entire program in one file.  (It's been awhile since I
> used it with D, so I don't quite remember the limitations, and maybe
> they've improved it.)
> 
> One way in which I prefer DOxygen over ddoc is that the documentation
> comments are a bit more compact.  Since I only have one screen, that
> sometimes makes things a lot more legible.  OTOH, the last time I used
> it I certainly got annoyed by it's limitations (in dealing with D).  But
> this time I really need to document private variables, so I guess
> there's no choice (unless I go with something like robodoc...ugh).

Why on earth would you need the documentation for private variables to be in 
the generated documentation? Only the module itself has access to them, so 
only someone editing the module will even care about them, and if they're 
editing the module, then they can see the comments on the variables directly. 
What does it buy you to them in the generated docs? They're not part of the 
API. Private variables seem exactly like the sort of thing that _shouldn't_ be 
in the generated docs.

- Jonathan M Davis
October 07, 2012
Re: ddoc - documenting private variables
On 10/06/2012 11:56 PM, Jonathan M Davis wrote:
> On Saturday, October 06, 2012 23:43:39 Charles Hixson wrote:
>> Well, DOxygen works ok if you don't use function contracts, and possibly
>> if you keep the entire program in one file.  (It's been awhile since I
>> used it with D, so I don't quite remember the limitations, and maybe
>> they've improved it.)
>>
>> One way in which I prefer DOxygen over ddoc is that the documentation
>> comments are a bit more compact.  Since I only have one screen, that
>> sometimes makes things a lot more legible.  OTOH, the last time I used
>> it I certainly got annoyed by it's limitations (in dealing with D).  But
>> this time I really need to document private variables, so I guess
>> there's no choice (unless I go with something like robodoc...ugh).
>
> Why on earth would you need the documentation for private variables to be in
> the generated documentation? Only the module itself has access to them, so
> only someone editing the module will even care about them, and if they're
> editing the module, then they can see the comments on the variables directly.
> What does it buy you to them in the generated docs? They're not part of the
> API. Private variables seem exactly like the sort of thing that _shouldn't_ be
> in the generated docs.
>
> - Jonathan M Davis
Because the documentation is primarily for *me*.  It's easy to generate 
another copy that doesn't document the private variables, but I need to 
know what the places I have designed to be tweaked by me (i.e., an 
implementer) are.  Five months from now I won't remember.
October 07, 2012
Re: ddoc - documenting private variables
On Saturday, 6 October 2012 at 20:23:11 UTC, Charles Hixson wrote:
> How does one generate documentation for private variables?  ...
>  Other, I mean, than switching to DOxygen (which has it's own 
> problems with D).

check this out from the announce group:
http://forum.dlang.org/thread/k4sa0j$73k$1@digitalmars.com#post-k4sa0j:2473k:241:40digitalmars.com
October 07, 2012
Re: ddoc - documenting private variables
On 10/07/2012 09:46 AM, Adam D. Ruppe wrote:
> On Saturday, 6 October 2012 at 20:23:11 UTC, Charles Hixson wrote:
>> How does one generate documentation for private variables? ...
>> Other, I mean, than switching to DOxygen (which has it's own problems
>> with D).
>
> check this out from the announce group:
> http://forum.dlang.org/thread/k4sa0j$73k$1@digitalmars.com#post-k4sa0j:2473k:241:40digitalmars.com
>

When I went there, my first thought was "Who rejected this and why?"
When I look more carefully, it looks like my intended use (generation of 
documentation for D code that has nothing to do with the web) is at best 
pretty much of an after-thought.  And the documentation doesn't indicate 
that it would be suitable for someone with my skill level.  (I.e., it 
looks like you need to read the code to figure it out.)

FWIW, I have absolutely NO knowledge of JSON, except that it's something 
to do with web pages (well, and it's a language or possibly a library). 
 So having to go through JSON as an intermediate step to generating the 
documentation doesn't look desirable.

OTOH, I'm an old Fortran programmer that switched over to Python (after 
looking at lots of other choices) awhile ago, because I didn't like the 
way C was so free with the use of pointers, etc.  My facility with D 
isn't all that great, especially when you start talking about templates 
and mix-in templates.  It's quite possible that people with a different 
background would find this much more approachable than I do.
October 07, 2012
Re: ddoc - documenting private variables
On Sunday, 7 October 2012 at 19:36:39 UTC, Charles Hixson wrote:
> FWIW, I have absolutely NO knowledge of JSON, except that it's 
> something to do with web pages (well, and it's a language or 
> possibly a library).


I haven't actually used that project (I just saw the link and 
figured it might help) but you can make json with dmd. Run dmd -X 
-D yourfile.d and it spits out yourfile.json.


But another option might be to just modify your copy of dmd to 
output private things too. Open the file dmd2/src/dmd/doc.c and 
search for the term PROTprivate. Simply comment that part so it 
doesn't return. For example:


void EnumDeclaration::emitComment(Scope *sc)
{
    if (prot() == PROTprivate)
        return;

Just comment that out and repeat for each time you see it. I 
count six occurrences of that in the dmd source. And then there's 
this:


void Declaration::emitComment(Scope *sc)
{
    //printf("Declaration::emitComment(%p '%s'), comment = 
'%s'\n", this,       toChars(), comment);
    //printf("type = %p\n", type);

    if (protection == PROTprivate || !ident ||
        (!type && !isCtorDeclaration() && !isAliasDeclaration()))
        return;


And you can probably just comment that protection clause there 
too.


Then recompile the dmd (make -f posix.mak on linux and I think 
make -f win32.mak on windows) and use your customized compiler.
October 08, 2012
Re: ddoc - documenting private variables
On 10/07/2012 12:33 PM, Adam D. Ruppe wrote:
> On Sunday, 7 October 2012 at 19:36:39 UTC, Charles Hixson wrote:
>> FWIW, I have absolutely NO knowledge of JSON, except that it's
>> something to do with web pages (well, and it's a language or possibly
>> a library).
>
>
> I haven't actually used that project (I just saw the link and figured it
> might help) but you can make json with dmd. Run dmd -X -D yourfile.d and
> it spits out yourfile.json.
>
>
> But another option might be to just modify your copy of dmd to output
> private things too. Open the file dmd2/src/dmd/doc.c and search for the
> term PROTprivate. Simply comment that part so it doesn't return. For
> example:
>
>
> void EnumDeclaration::emitComment(Scope *sc)
> {
> if (prot() == PROTprivate)
> return;
>
> Just comment that out and repeat for each time you see it. I count six
> occurrences of that in the dmd source. And then there's this:
>
>
> void Declaration::emitComment(Scope *sc)
> {
> //printf("Declaration::emitComment(%p '%s'), comment = '%s'\n", this,
> toChars(), comment);
> //printf("type = %p\n", type);
>
> if (protection == PROTprivate || !ident ||
> (!type && !isCtorDeclaration() && !isAliasDeclaration()))
> return;
>
>
> And you can probably just comment that protection clause there too.
>
>
> Then recompile the dmd (make -f posix.mak on linux and I think make -f
> win32.mak on windows) and use your customized compiler.

That seems, to me, a much more reasonable solution.  I'm going to flag 
this important.  But I'll probably use DOxygen, because I don't like the 
on-going maintenance, and because ddoc comments are too verbose (more in 
vertical space than in horizontal space).  I'll certainly keep that 
option in mind, however, in case I run into too many limits with DOxygen.
Top | Discussion index | About this forum | D home