update readme and mkdocs favicon

docs/api/modules/doc.md

@@ -1,5 +1,38 @@
 # doc
 
+
+Provides a consistent way to create documentation for prosperon elements. Objects are documented by adding docstrings directly to object-like things (functions, objects, ...), or to an object's own "doc object".
+
+Docstrings are set to the symbol `prosperon.DOC`
+
+```js
+// Suppose we have a module that returns a function
+function greet(name) { console.log("Hello, " + name) }
+
+// We can attach a docstring
+greet.doc = `
+Greets the user by name.
+`
+
+// A single function is a valid return!
+return greet
+```
+
+```js
+// Another way is to add a docstring object to an object
+var greet = {
+hello() { console.log('hello!') }
+}
+
+greet[prosperon.DOC] = {}
+greet[prosperon.DOC][prosperon.DOC] = 'An object full of different greeter functions'
+greet[prosperon.DOC].hello = 'A greeter that says, "hello!"'
+```
+
+
+**name**: The name of the person to greet.
+
+
 ### writeDocFile(obj, title) <sub>function</sub>
 
 Return a markdown string for a given obj, with an optional title.