On Tue, Dec 13, 2016 at 8:59 AM, Michael Orlitzky <m...@gentoo.org> wrote: > On 12/13/2016 06:11 AM, Mike Pagano wrote: >> >> You're absolutely right, Mike. It was the devmanual. >> >> I'm not a fan of having an empty usage. As the devmanual is written >> today, it is not optional. >> > > The devmanual is once again based on the awk script, which vaguely > implies that USAGE is required. For example, some other tags are optional: > > # @EXAMPLE: > # <optional; example usage> > > but the @USAGE does not say that it is: > > # The format of functions: > # @FUNCTION: foo > # @USAGE: <required arguments to foo> [optional arguments to foo] > # @RETURN: <whatever foo returns> > ... > > From now on, it would make more sense if the awk script conformed to the > devmanual rather than the other way around. I don't see any problem with > amending the devmanual, and then pestering the script maintainers to > play along.
The awk script does not generate an error for missing @USAGE, so it isn't even consistent with its own documentation.
