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.
