Documentation in Lisp

GNU Emacs is perhaps the most well-documented program in wide use. It would make sense to follow their documentation guidelines. Below is an abridged summary aimed towards Lisp programmers (quoted ad-verbum).

Document Everything

Every command, function, or variable intended for users to know about should have a documentation string. An internal variable or subroutine of a Lisp program might as well have a documentation string.

Documenting Functions vs. Variables

For a function, the first line should briefly answer the question, “What does this function do?” For a variable, the first line should briefly answer the question, “What does this value mean?”.

Docstring Structure

The first line of the documentation string should consist of one or two complete sentences that stand on their own as a summary. In particular, start the first line with a capital letter and end it with a period.

The first line should mention all the important arguments of the function, and should mention them in the order that they are written in a function call. If the function has many arguments, then it is not feasible to mention them all in the first line; in that case, the first line should mention the first few arguments, including the most important arguments.

Don’t limit the documentation string to one line; use as many lines as you need to explain the details of how to use the function or variable. Please use complete sentences for the rest of the text too.

Capitalise Arguments

When a function’s documentation string mentions the value of an argument of the function, use the argument name in capital letters as if it were a name for that value. Thus, the documentation string of the function eval refers to its first argument as FORM, because the actual argument name is form:

Evaluate FORM and return its value.

Also write metasyntactic variables in capital letters, such as when you show the decomposition of a list or vector into subunits, some of which may vary. ‘KEY’ and ‘VALUE’ in the following example illustrate this practice:

The argument TABLE should an alist whose elements have the form (KEY . VALUE). Here, KEY is ...

Surround Lisp symbols in curved single quotes

When a documentation string refers to a Lisp symbol, write it as it would be printed (which usually means in lower case), surrounding it with curved single quotes (‘..’). This might appear to contradict the policy of writing function argument values, but there is no real contradiction; the argument value is not the same thing as the symbol that the function uses to hold the value.

Grammar & Style

Write documentation strings in the active voice, not the passive, and in the present tense, not the future. For instance, use “Return a list containing A and B.” instead of “A list containing A and B will be returned.”

For consistency, phrase the verb in the first sentence of a function’s documentation string as an imperative — for instance, use “Return the cons of A and B.” in preference to “Returns the cons of A and B.” Usually it looks good to do likewise for the rest of the first paragraph. Subsequent paragraphs usually look better if each sentence is indicative and has a proper subject.

The documentation string for a function that is a yes-or-no predicate should start with words such as “Return t if”, to indicate explicitly what constitutes truth. The word “return” avoids starting the sentence with lower-case “t”, which could be somewhat distracting.

Try to avoid using abbreviations such as “e.g.” (for “for example”), “i.e.” (for “that is”), “no.” (for “number”), “c.f.” (for “in contrast to”) and “w.r.t.” (for “with respect to”) as much as possible. It is almost always clearer and easier to read the expanded version.

Other Tips

Do not indent subsequent lines of a documentation string so that the text is lined up in the source code with the text of the first line. This looks nice in the source code, but looks bizarre when users view the documentation. Remember that the indentation before the starting double-quote is not part of the string! Do not start or end a documentation string with whitespace.

The documentation string for a variable that is a yes-or-no flag should start with words such as “Non-nil means”, to make it clear that all non-nil values are equivalent and indicate explicitly what nil and non-nil mean.

--

--

--

Masters in Quantitative Finance. Writing Computer Science articles and notes on topics that interest me, with a tendency towards writing about Lisp & Swift

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Hacking MISDIRECTION- VulnHub

How to use Unirobot Demo

Flutter App integration with Multiple Technologies

5 Awesome Open Source Software In 2020

Adding Scheduled/Background Tasks to Django

Flutter In-app education plugin

Android — One and two way Databinding

Via Protocol: February 2022✌️

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Ashok Khanna

Ashok Khanna

Masters in Quantitative Finance. Writing Computer Science articles and notes on topics that interest me, with a tendency towards writing about Lisp & Swift

More from Medium

Letter Box Alert with Bolt IoT

Vendible selects Onfido to secure blockchain transactions with trusted identity verification.

Svelte Deployments with Fathym LowCodeUnit

Minecraft server on debian, the full explanation…

Header image