X-Git-Url: https://code.consxy.com/gitweb/gitweb.cgi?p=sheep;a=blobdiff_plain;f=README.md;h=3d1ce91485879a947d8630bfbd384a46523117b5;hp=c059be9e2b54a1ba891c95a59475855899a86a93;hb=d898031;hpb=b9787e5bd86fb01594c23c2147bde306ea5b3bf5

diff --git a/README.md b/README.md
index c059be9..3d1ce91 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,103 @@
 # Common Lisp Document Generator
 
-Enforcement of documentation guidelines for my Common Lisp Projects, as well as conversion to markdown for github repositories.
+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](https://github.com/frankduncan/docgen/releases/download/0.3/docgen_0.3.tar.gz)
+
+## Usage
+
+See the [wiki](https://github.com/frankduncan/docgen/wiki) for usage information (generated by this package).
+
+To see how that page was created, take a look at bin/generatedocs.sh
+
+## Package documentation
+
+Packages are documented by sections broken up by one empty line, with the first section limited to 120 characters.
+
+## Structure/Condition documentation
+
+Requirements are the same as the package documentation.
+
+## Variable 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.
+
+### 
+
+## 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:
+
+### Header section
+
+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 *
+
+### Arguments and values section:
+
+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.
+
+### Description
+
+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.
+
+### Examples
+
+This section is optional.
+
+Examples are of the form:  example-code => example result