Re: Command documentation policy

[Colin Watson]

On Tue, Jan 22, 2013 at 05:12:18PM +0000, Colin Watson wrote:
> On Tue, Jan 22, 2013 at 05:08:51PM +0400, Andrey Borzenkov wrote:
> > Quit a number of commands are not documented. Is it intentional
> > (because they are not considered "user level API")? Should
> > documentation for them go into grub or grub-dev?
> 
> I spent some time documenting the list of commands a while back, but I
> never completed the project: what you're seeing is simply how far I got
> before getting distracted by other things.  IMO all commands should be
> documented in grub.texi.

Oh, and to be clear: yes, there are some situations where something is
intentionally undocumented (although not really all that many, I think).
However, I don't think that justifies leaving it out of grub.texi
entirely, because that runs the risk of somebody else coming along later
and not realising that this thing was intentionally undocumented.

The approach I'd recommend for such cases is to add a comment (@c or
@ignore / @end ignore) to grub.texi explaining that such-and-such a
command is intentionally undocumented.  That way, it doesn't show up for
users in formatted documentation, but anyone editing the document will
see it.

-- 
Colin Watson                                       address@hidden