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
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 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 reply 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
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


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.
Oct 07 2012
prev 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 reply "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
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