I’m bringing here the following text from an ancient topic in the old mailing list, which proposes a convention for how we should phrase the help text for the various commands and how that code should look like.
We’re doing much better by now, but we’re still inconsistent in a few places. So let’s see if we can eventually converge.
Here is a proposal, taking the assert command as an example.
Starts with a verb, inline, no punctuation.
var shortAssertHelp = i18n.G(`Adds an assertion to the system`)
Starts with “The <name> command …”, backquoted, broken out lines, proper punctuation.
var longAssertHelp = i18n.G(`
The ack command tries to add an assertion to the system assertion database.
The assertion may also be a newer revision of a preexisting assertion that
it will replace.
The longAssertHelp will likely have to be stripped out of its leading newline, but I suggest we keep the format like that, both to make reading the likely display result easier, and to encourage slightly more descriptive user-oriented comments on our commands.