ddoc - documenting private variables

[Jonathan M Davis]

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