Re: Steve Donovan's ldoc: recognized function declaration formats and possible bug

[Lorenzo Donati <lorenzodonatibz@...>]

On 13/06/2011 13.54, steve donovan wrote:
> On Mon, Jun 13, 2011 at 1:45 PM, Lorenzo Donati
> <lorenzodonatibz@interfree.it>  wrote:
> > Of course not for building API documentation, but for "in-house"
> > documentation. Sometimes it happens that a long module has to be
> > refactored/changed/extended and some of its "private" local functions are to
> > be reused (or made public).
>
> This is a good argument. I would suggest however that such private
> functions/tables/etc live in their own 'documentation namespace', e.g.
> 'Local Functions' so that the external user of the API won't be
> confused.
Yes, of course. In fact I was about to suggest that ldoc could have a 
switch to allow private vs. public documentation generation option.

Then add a @private tag to whatever entity you want not to appear in the 
API docs.

The cherry on top would be that @private were followed by a keyword, to 
differentiate between different kind of "privateness".

Then you could do, say (syntax to be designed better):

ldoc -private

to generate full documentation on internal stuff, or

ldoc -private "utility,broken"

to generate private docs only for items tagged as

@private utility

and

@private broken


> steve d.