Enforcement of documentation guidelines for my Common Lisp Projects, as well as conversion to markdown for my github repositories.
I wish I had aspirations for this being some standard that someone else might follow, but realistically I'm just irritated at my own laziness with regard to documentation, so I wrote a solution. The forceful nature of the validator is really just because I didn't want to write a smarter parser. As an added bonus, all the docs now look the same when I look at them in the repl, so that's kind of nice.
If you like, you can download it
See Reference for usage information (generated by this package).
To see how that page was created, take a look at bin/generatedocs.sh
Packages are documented by sections broken up by one empty line, with the first section limited to 120 characters.
Requirements are the same as the package documentation.
Variables should follow the template:
*VARIABLE*
VALUE TYPE:
a generalized boolean
INITIAL VALUE:
NIL
DESCRIPTION:
*VARIABLE* is expected to be a boolean, but
most anything can be it.
EXAMPLES:
(let ((*variable* t)) (go)) => let-it-go
There are three required sections and one optional section. VALUE TYPE, INITIAL VALUE, and DESCRIPTION are freeform, with the EXAMPLES section following the same rules as below in the function documentation.
Functions should follow the template:
FUNC PATH => RESULT
RESULT: SUCCESS-RESULTS | FAILURE-RESULT
SUCCESS-RESULTS: SUCCESS-RESULT*
SUCCESS-RESULT: (:success FILENAME)
FAILURE-RESULT: (:failure FILENAME MSG)
ARGUMENTS AND VALUES:
PATH: a pathname
FILENAME: the file this func was run on
MSG: a string containing the failure message
DESCRIPTION:
FUNC runs all the things against a file located at PATH and returns
as soon as the first func error is found.
EXAMPLES:
(func #P\"path/to/file.lisp\" t) => (:success \"path/to/file.lisp\")
(func #P\"path/to/error.lisp\" nil) => (:failure \"path/to/error.lisp\" \"Error msg\")
There are four sections to each function definition:
Arguments should all be upper case, but &rest, &optional, and &key should be lower case. Arguments are seperated by a space.
Results should also be upper case, and in the case of values, separated by commas.
Types can be further elucidated by providing more information either as a list of options seperated by pipes, a tuple contained in parens, or a list denoted by an *
All the types that weren't broken down into subtypes must be explained. The form is type name in all upper case, a colon, then a description. That description can have upper case type names in it which will then get italicized later.
Descriptins should be indented two spaces, and not longer than 120 characters wide. Like the arguments and values, upper cased types will be italicized later.
This section is optional.
Examples are of the form: example-code => example result