From 80036f0b9ee60205d18522c7ce06a3fa79fa1e13 Mon Sep 17 00:00:00 2001
From: Paul Liverman III <paul.liverman.iii@gmail.com>
Date: Tue, 24 Apr 2018 22:59:07 -0700
Subject: [PATCH] more wip docs

---
 views/docs/v1.moon | 96 ++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 92 insertions(+), 4 deletions(-)

diff --git a/views/docs/v1.moon b/views/docs/v1.moon
index 8686202..c5069f8 100644
--- a/views/docs/v1.moon
+++ b/views/docs/v1.moon
@@ -34,6 +34,7 @@ class Docs_1 extends Widget
 
     style -> raw "h3 { font-family: monospace; }"
 
+    a name: "top"
     ol style: "font-family: monospace;", ->
       li ->
         a href: "#endpoints", "Endpoints"
@@ -76,6 +77,7 @@ class Docs_1 extends Widget
       a href: "#errors", "Errors"
       text " below for more info on that."
 
+    a href: "#top", "back to top"
     a name: "auth"
     h2 "Authorization"
 
@@ -96,6 +98,7 @@ class Docs_1 extends Widget
       a href: @url_for("index"), "the web interface"
       text " to get started. You can also delete existing API keys there."
 
+    a href: "#top", "back to top"
     a name: "tasks"
     h2 "Tasks"
 
@@ -126,6 +129,7 @@ class Docs_1 extends Widget
 
     task_list!
 
+    a href: "#top", "back to top"
     a name: "new"
     h3 "/new"
 
@@ -135,7 +139,7 @@ class Docs_1 extends Widget
       text " string with valid authorization and a new task item will be returned. Here's an example response:"
 
     blockquote ->
-      code style: "white-space: normal;", '{ "success": true,\n  "task": { "id": 4, "user_id": 2, "content": "Get a new API key.", "done": false, "created_at": "2018-04-25 04:27:47", "updated_at": "2018-04-25 04:27:47" } \n}'
+      code style: "white-space: normal;", '{ "success": true, "task": { "id": 4, "user_id": 2, "content": "Get a new API key.", "done": false, "created_at": "2018-04-25 04:27:47", "updated_at": "2018-04-25 04:27:47" } }'
 
     p ->
       text "This same format is used to return any task, whether it is as a response to these simple queries, or as part of an array returned by "
@@ -144,42 +148,126 @@ class Docs_1 extends Widget
       code "/random"
       text "."
 
+    a href: "#top", "back to top"
     a name: "get"
     h3 "/get"
 
+    p ->
+      text "Select a task by its "
+      code "id"
+      text " (an integer), or its "
+      code "content"
+      text " (a string). Example request:"
+
+    blockquote ->
+      code '{ "id": 5 }'
+
+    p ->
+      text "See "
+      a href: "#new", "/new"
+      text " for an example response."
+
+    a href: "#top", "back to top"
     a name: "do"
     h3 "/do"
 
+    p "Marks a task as done. Returns success even if the task was already marked done. Example request:"
+
+    blockquote ->
+      code '{ "content": "that one thing you need to remember to do" }'
+
+    p ->
+      text "See "
+      a href: "#new", "/new"
+      text " for an example response."
+
+    a href: "#top", "back to top"
     a name: "undo"
     h3 "/undo"
 
+    p ->
+      text "Marks a task as not done. Returns success even if the task was already marked not done. See "
+      a href: "#new", "/new"
+      text " for an example response."
+
+    a href: "#top", "back to top"
     a name: "delete"
     h3 "/delete"
 
+    p ->
+      text "Deletes a task. Just returns "
+      code '{ "success": true }'
+      text " if successful."
+
+    a href: "#top", "back to top"
     a name: "list"
     h3 "/list"
 
+    p ->
+      text "Returns an array of task objects (see "
+      a href: "#new", "/new"
+      text " for an example task object). All arguments are optional:"
+
+    element "table", ->
+      thead ->
+        tr ->
+          th "Argument"
+          th "Type"
+          th "Default"
+      tbody ->
+        tr ->
+          td -> code "count"
+          td "integer"
+          td 50
+        tr ->
+          td -> code "done"
+          td "boolean"
+          td "returns ALL tasks if not set"
+        tr ->
+          td -> code "page"
+          td "integer"
+          td 1
+        tr ->
+          td -> code "order"
+          td "'asc'/'desc'"
+          td "'asc' (oldest first)"
+
+    p ->
+      text "If you request a page beyond the number of pages available, the last page will be returned. "
+      code "page"
+      text " is specified in the response, so you will know if you have received a different page than requested. Additionally, "
+      code "pages"
+      text " is defined in all requests to "
+      code "/list"
+      text ". Example response (with tasks trimmed out):"
+
+    blockquote ->
+      code '{ "success": true, page: 5, pages: 10, tasks: [ /* task list omitted */ ] }'
+
+    a href: "#top", "back to top"
     a name: "random"
     h3 "/random"
 
+    a href: "#top", "back to top"
     a name: "keys"
     h2 "API Keys"
 
+    a href: "#top", "back to top"
     a name: "new-key"
     h3 "/key/new"
 
+    a href: "#top", "back to top"
     a name: "delete-key"
     h3 "/key/delete"
 
+    a href: "#top", "back to top"
     a name: "errors"
     h2 "Errors"
 
+    a href: "#top", "back to top"
     a name: "rate-limit"
     h2 "Rate Limiting"
 
     p "At this time there is no rate limiting. This will be developed when needed, and the API documentation updated to reflect that, with at least 2 months' warning."
 
--- /list { count: #, done: bool, page: #, order: asc/desc } (if done not specified, returns all,
---                        default count is 50, default page is 1, default order is latest first
--- also returns page: #, pages: #, tasks: []
 -- /random { count: #, done: bool } (both args optional, defaults count 1, done false)