From fb013773c3ef4f6ee2b2e1c0dd516c563c0fb6ba Mon Sep 17 00:00:00 2001
From: Blake DeMarcy <ofunknowndescent@gmail.com>
Date: Sun, 2 Apr 2017 23:51:44 -0500
Subject: [PATCH] documentation changes

---
 src/exceptions.py | 11 +++++++++++
 src/formatting.py |  5 +++++
 src/schema.py     | 37 +++++++++++++++++++++++++++++++++++++
 3 files changed, 53 insertions(+)

diff --git a/src/exceptions.py b/src/exceptions.py
index a34e02c..c9e449f 100644
--- a/src/exceptions.py
+++ b/src/exceptions.py
@@ -1,3 +1,14 @@
+"""
+These exceptions create schema objects to send back to the client.
+The new error codes have not been fully documented since ditching
+the prototype but there are less of them and the handling is much
+more robust and less verbose in the source code.
+
+At any point of the API's codepath, these may be raised and will be
+captured by the request handler. Their schema is then sent back to
+the client.
+"""
+
 from src.schema import error
 
 
diff --git a/src/formatting.py b/src/formatting.py
index d327a24..abf13f5 100644
--- a/src/formatting.py
+++ b/src/formatting.py
@@ -1,3 +1,8 @@
+"""
+This module is not complete and none of its functions are currently
+used elsewhere. Subject to major refactoring.
+"""
+
 from markdown import markdown
 from html import escape
 import re
diff --git a/src/schema.py b/src/schema.py
index 0851ffa..85de132 100644
--- a/src/schema.py
+++ b/src/schema.py
@@ -1,3 +1,40 @@
+"""
+This module provides functions that return API objects in
+a clearly defined, consistent manner. Schmea representing
+data types mirror the column order used by the sqlite
+database. An sql object can be unpacked by using star
+expansion as an argument, such as thread(*sql_thread_obj)
+
+Each response has a base layout as follows:
+
+{
+  "error":   false, // boolean false or error object
+  "data":    null,  // null or the requested data from endpoint.
+  "usermap": {}     // a potentially empty object mapping user_ids to their objects
+}
+
+If "error" is true, it looks like this:
+
+{
+  "error": {
+      "code": an integer from 0 to 5,
+      "description": a string describing the error in detail.
+}
+  "data": null   // ALWAYS null if error is not false
+  "usermap": {}  // ALWAYS empty if error is not false
+}
+
+"data" can be anything. It could be a boolean, it could be a string,
+object, anything. The return value for an endpoint is described clearly
+in its documentation. However, no endpoint will EVER return null. If
+"data" is null, then "error" is filled.
+
+"usermap" is filled with objects whenever users are present in
+"data". its keys are all the user_ids that occur in the "data"
+object. Use this to get information about users, as follows:
+usermap[id]["user_name"]
+"""
+
 def base():
     return {
         "error": False,