ddoc - documenting private variables

[Charles Hixson]

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.