How does one generate documentation for private variables?  ...  Other, I mean, than switching to DOxygen (which has it's own problems with D).

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

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.

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

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

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.

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

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.

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.

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.