www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - ddoc - documenting private variables

reply Charles Hixson <charleshixsn earthlink.net> writes:
How does one generate documentation for private variables?  ...  Other, 
I mean, than switching to DOxygen (which has it's own problems with D).
Oct 06 2012
next sibling parent reply Jonathan M Davis <jmdavisProg gmx.com> writes:
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
Oct 06 2012
parent reply Charles Hixson <charleshixsn earthlink.net> writes:
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).
Oct 06 2012
parent Charles Hixson <charleshixsn earthlink.net> writes:
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

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.
Oct 07 2012
prev sibling next sibling parent "Era Scarecrow" <rtcvb32 yahoo.com> writes:
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.
Oct 06 2012
prev sibling next sibling parent Jonathan M Davis <jmdavisProg gmx.com> writes:
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
Oct 06 2012
prev sibling next sibling parent reply "Adam D. Ruppe" <destructionator gmail.com> writes:
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
Oct 07 2012
parent reply Charles Hixson <charleshixsn earthlink.net> writes:
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.
Oct 07 2012
parent Charles Hixson <charleshixsn earthlink.net> writes:
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.
Oct 08 2012
prev sibling parent "Adam D. Ruppe" <destructionator gmail.com> writes:
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.
Oct 07 2012