Re: [gentoo-dev] [PATCH 1/1] kernel-2.eclass: Add required @USAGE documentation to functions.

[Michael Orlitzky]

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.