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