uLisp Release 4.3 now 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.
To download the latest release of uLisp see Download 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 on a new line 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 #. macro to evaluate a format statement when the definition is read in. For example:
(defun sq (x) #.(format nil "(sq num)~%Returns the square of num.") (* x x))
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.
I look forward to feedback about this new feature!