code.consxy.com Git - sheep/blob - README.md

   1 # Common Lisp Document Generator
   2
   3 Enforcement of documentation guidelines for my Common Lisp Projects, as well as conversion to markdown for my github repositories.
   4
   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.
   6
   7 If you like, you can [download it](https://github.com/frankduncan/docgen/releases/download/0.1/docgen_0.1.tar.gz)
   8
   9 ## Usage
  10
  11 See the [wiki](https://github.com/frankduncan/docgen/wiki) for usage information (generated by this package).
  12
  13 To see how that page was created, take a look at bin/generatedocs.sh
  14
  15 ## Package documentation
  16
  17 Packages are documented by sections broken up by one empty line, with the first section limited to 120 characters.
  18
  19 ## Structure/Condition documentation
  20
  21 Requirements are the same as the package
  22
  23 ## Function documentation
  24
  25 Functions should follow the template:
  26
  27 ````
  28 FUNC PATH => RESULT
  29
  30   RESULT: SUCCESS-RESULTS | FAILURE-RESULT
  31   SUCCESS-RESULTS: SUCCESS-RESULT*
  32   SUCCESS-RESULT: (:success FILENAME)
  33   FAILURE-RESULT: (:failure FILENAME MSG)
  34
  35 ARGUMENTS AND VALUES:
  36
  37   PATH: a pathname
  38   FILENAME: the file this func was run on
  39   MSG: a string containing the failure message
  40
  41 DESCRIPTION:
  42
  43   FUNC runs all the things against a file located at PATH and returns
  44   as soon as the first func error is found.
  45
  46 EXAMPLES:
  47
  48   (func #P\"path/to/file.lisp\" t) => (:success \"path/to/file.lisp\")
  49   (func #P\"path/to/error.lisp\" nil) => (:failure \"path/to/error.lisp\" \"Error msg\")
  50 ````
  51
  52 There are four sections to each function definition:
  53
  54 ### Header section
  55
  56 Arguments should all be upper case, but &rest, &optional, and &key should be lower case.  Arguments are seperated by a space.
  57
  58 Results should also be upper case, and in the case of values, separated by commas.
  59
  60 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 *
  61
  62 ### Arguments and values section:
  63
  64 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.
  65
  66 ### Description
  67
  68 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.
  69
  70 ### Examples
  71
  72 This section is optional.
  73
  74 Examples are of the form:  example-code => example result