1 # Common Lisp Document Generator
3 Enforcement of documentation guidelines for my Common Lisp Projects, as well as conversion to markdown for my github repositories.
5 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.
7 If you like, you can [download it](https://consxy.com/sheep/releases/0.3/docgen_0.3.tar.gz)
11 See [Reference](https://consxy.com/sheep/reference.html) for usage information (generated by this package).
13 To see how that page was created, take a look at bin/generatedocs.sh
15 ## Package documentation
17 Packages are documented by sections broken up by one empty line, with the first section limited to 120 characters.
19 ## Structure/Condition documentation
21 Requirements are the same as the package documentation.
23 ## Variable documentation
25 Variables should follow the template:
40 *VARIABLE* is expected to be a boolean, but
41 most anything can be it.
45 (let ((*variable* t)) (go)) => let-it-go
48 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.
52 ## Function documentation
54 Functions should follow the template:
59 RESULT: SUCCESS-RESULTS | FAILURE-RESULT
60 SUCCESS-RESULTS: SUCCESS-RESULT*
61 SUCCESS-RESULT: (:success FILENAME)
62 FAILURE-RESULT: (:failure FILENAME MSG)
67 FILENAME: the file this func was run on
68 MSG: a string containing the failure message
72 FUNC runs all the things against a file located at PATH and returns
73 as soon as the first func error is found.
77 (func #P\"path/to/file.lisp\" t) => (:success \"path/to/file.lisp\")
78 (func #P\"path/to/error.lisp\" nil) => (:failure \"path/to/error.lisp\" \"Error msg\")
81 There are four sections to each function definition:
85 Arguments should all be upper case, but &rest, &optional, and &key should be lower case. Arguments are seperated by a space.
87 Results should also be upper case, and in the case of values, separated by commas.
89 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 *
91 ### Arguments and values section:
93 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.
97 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.
101 This section is optional.
103 Examples are of the form: example-code => example result