| 1 |
On Tue, Dec 13, 2016 at 8:59 AM, Michael Orlitzky <mjo@g.o> wrote: |
| 2 |
> On 12/13/2016 06:11 AM, Mike Pagano wrote: |
| 3 |
>> |
| 4 |
>> You're absolutely right, Mike. It was the devmanual. |
| 5 |
>> |
| 6 |
>> I'm not a fan of having an empty usage. As the devmanual is written |
| 7 |
>> today, it is not optional. |
| 8 |
>> |
| 9 |
> |
| 10 |
> The devmanual is once again based on the awk script, which vaguely |
| 11 |
> implies that USAGE is required. For example, some other tags are optional: |
| 12 |
> |
| 13 |
> # @EXAMPLE: |
| 14 |
> # <optional; example usage> |
| 15 |
> |
| 16 |
> but the @USAGE does not say that it is: |
| 17 |
> |
| 18 |
> # The format of functions: |
| 19 |
> # @FUNCTION: foo |
| 20 |
> # @USAGE: <required arguments to foo> [optional arguments to foo] |
| 21 |
> # @RETURN: <whatever foo returns> |
| 22 |
> ... |
| 23 |
> |
| 24 |
> From now on, it would make more sense if the awk script conformed to the |
| 25 |
> devmanual rather than the other way around. I don't see any problem with |
| 26 |
> amending the devmanual, and then pestering the script maintainers to |
| 27 |
> play along. |
| 28 |
|
| 29 |
The awk script does not generate an error for missing @USAGE, so it |
| 30 |
isn't even consistent with its own documentation. |
Archives