From baeff81f89f80751a8cb7257c750f3b4b1b8b36f Mon Sep 17 00:00:00 2001
From: Griffin Smith <root@gws.fyi>
Date: Fri, 1 Feb 2019 11:39:14 -0500
Subject: [PATCH] docs: Bolster docs on setup, usage and config

Add docs for all config variables and interactive commands, and list
commands in the README
---
 README.org       | 43 ++++++++++++++++++++++++++++++++++++++++++-
 org-clubhouse.el | 10 ++++++++--
 2 files changed, 50 insertions(+), 3 deletions(-)

diff --git a/README.org b/README.org
index 8dd8fc8d2..b7548c347 100644
--- a/README.org
+++ b/README.org
@@ -34,9 +34,50 @@ Simple, unopinionated integration between Emacs's [[https://orgmode.org/][org-mo
 
 * Setup
 
-Once setup, you'll need to set two global config vars.
+Once installed, you'll need to set two global config vars:
 
 #+BEGIN_SRC emacs-lisp
 (setq org-clubhouse-auth-token "<your-token>"
       org-clubhouse-team-name "<your-team-name>")
 #+END_SRC
+
+You can generate a new personal API token by going to the "API Tokens" tab on
+the "Settings" page in the clubhouse UI.
+
+Org-clubhouse can be configured to update the status of stories as you update
+their todo-keyword in org-mode. To opt-into this behavior, set the
+~org-clubhouse-mode~ minor-mode:
+
+#+BEGIN_SRC emacs-lisp
+(add-hook 'org-mode-hook #'org-clubhouse-mode nil nil)
+#+END_SRC
+
+* Usage
+
+In addition to updating the status of stories linked to clubhouse tickets,
+org-clubhouse provides the following commands:
+
+- ~org-clubhouse-create-story~
+  Creates a new Clubhouse story from the current headline, or if a region of
+  headlines is selected bulk-creates stories with all those headlines
+- ~org-clubhouse-create-epic~
+  Creates a new Clubhouse epic from the current headline, or if a region of
+  headlines is selected bulk-creates epics with all those headlines
+- ~org-clubhouse-create-story-with-task-list~
+  Creates a Clubhouse story from the current headline, making all direct
+  children of the headline into tasks in the task list of the story
+- ~org-clubhouse-push-task-list~
+  Writes each child element of the current clubhouse element as a task list
+  item of the associated clubhouse ID.
+- ~org-clubhouse-update-story-title~
+  Updates the title of the Clubhouse story linked to the current headline with
+  the text of the headline
+- ~org-clubhouse-headlines-from-query~
+  Create org-mode headlines from a clubhouse query at the cursor's current
+  position, prompting for the headline indentation level and clubhouse query
+  text
+
+* Configuration
+
+Refer to the beginning of the [[https://github.com/urbint/org-clubhouse/blob/master/org-clubhouse.el][~org-clubhouse.el~]] file in this repository for
+documentation on all supported configuration variables
diff --git a/org-clubhouse.el b/org-clubhouse.el
index 442e73ede..456f372bd 100644
--- a/org-clubhouse.el
+++ b/org-clubhouse.el
@@ -73,7 +73,10 @@ not be prompted")
     ("PR"     . "Review")
     ("DONE"   . "Merged")
     ("[X]"    . "Merged")
-    ("CLOSED" . "Merged")))
+    ("CLOSED" . "Merged"))
+  "Alist mapping org-mode todo keywords to their corresponding states in
+  Clubhouse. In `org-clubhouse-mode', moving headlines to these todo keywords
+  will update to the corresponding status in Clubhouse")
 
 (defvar org-clubhouse-story-types
   '(("feature" . "Feature")
@@ -86,7 +89,8 @@ not be prompted")
     ("chore"   . "Chore")
     ("prompt"  . "**Prompt each time (do not set a default story type)**")))
 
-(defvar org-clubhouse-default-state "Proposed")
+(defvar org-clubhouse-default-state "Proposed"
+  "Default state to create all new stories in")
 
 ;;;
 ;;; Utilities
@@ -693,6 +697,8 @@ allows manually passing a clubhouse ID and list of org-element plists to write"
 ;;;
 
 (defun org-clubhouse-update-story-title ()
+  "Updates the title of the Clubhouse story linked to the current headline with
+the text of the headline"
   (interactive)
 
   (when-let (clubhouse-id (org-element-clubhouse-id))