#docerr

[mentalisttraceur-software]

docerr

A little touch I've started to add to my command-line tools, inspired by docopt, is an "errors" section which is pretty clear to humans, and yet tells you precise API information. For example:

$ cdexec --help Execute a command in the given directory. If no command is given, just check if going into the directory works. Usage: cdexec [--] <directory> [<command> [<argument>]...] cdexec (--help | --version) [<ignored>]... Options: -h --help show this help text -V --version show version information Errors: need directory argument bad option: <option> error writing output: <...> error changing directory: <directory>: <...> error executing command: <command>: <...>

That describes every error this program can have, and those exact words will be the first thing written to standard error as part of the error message when those errors happen (prefixed only by "cdexec: ", since it is a universal convention for command-line programs to prefix their errors with the name they were invoked as).

So if you ever want to use this command in a script or program that handles a specific error, you can capture standard error and check for one of those strings in a rigorous predictable way. But you didn't have to know or think about any of that for that "Errors:" section to still be clear and informative in a "big picture" way.

[mentalisttraceur-software]

docexit

This doesn't come up nearly as often as "docerr" for me, because most programs can reasonably just exit with success or failure and save all specificity for stderr, but I have a similar little touch for a program to document its exit statuses in help text.

For example, a diff program could use this section in its help text like this:

Exits:

    0 if the input files are the same

    1 if the input files differ

    2 if there was an error

And for ssh it would look like this:

Exits:

    0-255 exit status of the remote command

    255 if there was an error in ssh

I personally would include this whenever the conventional expectations of exit behavior would be wrong or misleading.