Integral documentation
uLisp includes integral documentation for all the built-in functions, which you can display in the Arduino Serial Monitor or a terminal used with uLisp:
You can also add documentation to the functions you define in uLisp, in the same format as the built-in documentation. The documentation for the built-in functions is stored in flash memory, and has no impact on the performance of uLisp.
Displaying the documentation for a built-in function
To display documentation about any built-in function or special form, use the ? function. For example:
> (? assoc) (assoc key list) Looks up a key in an association list of (key . value) pairs, and returns the matching pair, or nil if no pair is found.
The documentation consists of a prototype, showing the arguments that the function takes, followed by a description of the arguments and function's action.
Optional arguments
Optional arguments are shown in the parameter list in square brackets. For example:
> (? pprintall) (pprintall [str]) Pretty-prints the definition of every function and variable defined in the uLisp workspace. If str is specified it prints to the specified stream. It returns no value.
Variable number of arguments
An asterisk indicates that there can be one or more arguments of the same type. For example:
> (? =) (= number*) Returns t if all the arguments, which must be numbers, are numerically equal,
and nil otherwise.
Adding documentation to your own functions
If you want to add documentation to your own functions, simply add the documentation string after the parameter list in the defun; for example:
(defun sq (x) "Returns the square of its argument." (* x x))
It will then show the documentation in the same way as for the built-in functions:
> (? sq)
Returns the square of its argument.
If you want to make your documentation match the built-in documentation, with a prototype showing the parameters followed by a description on the next line(s), one way is to use the format statement to return a string with a line break in it. For example:
(defun sq (x) #.(format nil "(sq num)~%Returns the square of num.") (* x x))
Prefixing the format statement with the #. macro causes it to be evaluated to a string when it's read in.
This will then give:
> (? sq)
(sq num)
Returns the square of num.
The documentation function
The (? symbol) special form is a more convenient synonym for the documentation function:
(documentation 'symbol)
This is similar, except that you need to quote the symbol, and the documentation is returned as a Lisp string. It's useful if you want to process the documentation string in a program.
For compatibility with the standard Common Lisp documentation function this also takes an optional second argument, which is ignored in uLisp.