Help: documenting-verbs

Showing help on 'documenting-verbs'

Documenting verbs

A verb's documentation is the string literals at the very top of its code. help $thing and help $thing:verb read them, and so does the AI tool layer, so documented verbs double as tool definitions.

First line: the signature, starting with a colon.
":verb(arg, ?optional) => result";

Then prose, one idea per string:
"Returns the nearest exit to who, or $nothing.";
"Ties go to the exit listed first.";

Optionally, annotate parameters. help $thing:verb shows these as a parameter list:
"@param who OBJ the player to measure from";
"@param radius FLOAT [optional] how far to look, in metres";
"@enum mode fast,exact";
"@tool Short description for AI tool use";

To see which verbs on an object still need docs, use @doc-coverage <object>.

To draft docs with AI help, use @autodoc <object>:<verb> (Autocoding feature). Read each suggestion against the code before accepting it.

See also: help $verb_help, help utilities.