bugfixes: require 'assoc, add better documentation, and autoloads. :)

tumblesocks-api.el

@@ -1,29 +1,41 @@
 ;; tumblesocks-api.el -- functions for talking with tumblr
 ;; Copyright (C) 2012 gcr
 
+(require 'assoc)
 (require 'oauth)
 (require 'json)
 (provide 'tumblesocks-api)
 
 (defcustom tumblesocks-consumer-key
   "5xqkcJNRSGj3TokMQDJf3FzE8246DHvw8sNJWNn54fs2z0AhYr"
-  "Your tumblr app's consumer API key. This goes hand-in-hasd
-with `tumblesocks-secret-key'."
-  :type 'string)
+  "Our Tumblr OAuth consumer API key.
+
+This goes hand-in-hand with `tumblesocks-secret-key'.
+
+If you need to register your own app, do that at
+http://www.tumblr.com/oauth/apps"
+  :type 'string
+  :group 'tumblesocks)
 
 (defcustom tumblesocks-secret-key
   "juLG1T866ZG964ybgGCu1EntFMo5eQuHth1SKCqL2mdMzNIL1Q"
-  "Your tumbler app's secret key. Works in tandem with
-`tumblesocks-consumer-key'."
-  :type 'string)
+  "Our Tumblr OAuth consumer secret key.
+
+This goes hand-in-hand with `tumblesocks-consumer-key'.
+
+If you need to register your own app, do that at
+http://www.tumblr.com/oauth/apps"
+  :type 'string
+  :group 'tumblesocks)
 
 (defcustom tumblesocks-blog nil
   "Your blog name, like xxx.tumblr.com.
 
 This variable affects many functions that depend on blogs. For
 example, `tumblesocks-api-blog-posts' will consult this variable
 to pick which block to list posts for, so if you want to temporarily ask for a different blog, rebind this."
-  :type 'string)
+  :type 'string
+  :group 'tumblesocks)
 
 (defvar tumblesocks-token nil)
 
@@ -77,7 +89,7 @@ call `tumblesocks-api-reauthenticate' after this."
 
 (defun tumblesocks-api-test-auth ()
   (interactive)
-  (unless tumblesocks-blog (error "Please set `tumblesocks-blog'"))
+  (unless tumblesocks-blog (error "Please set the `tumblesocks-blog' variable. See https://github.com/gcr/tumblesocks for help getting Tumblesocks working."))
   (condition-case nil
       (message (concat "Hello, "
                        (cdr (assq 'name

tumblesocks-compose.el

@@ -1,3 +1,5 @@
+
+(require 'assoc)
 (require 'tumblesocks-user)
 (require 'tumblesocks-api)
 (require 'htmlize)
@@ -9,14 +11,17 @@
 (defvar tumblesocks-compose-finish-action
   '(lambda () (call-interactively 'tumblesocks-text-post-from-buffer))
   "The action to run when finishing posting")
-(defvar tumblesocks-compose-continuation
-  nil "Optional action to run when finishing editing or posting")
+(defvar tumblesocks-compose-continuation nil
+  "Optional action to run when finishing editing or posting.
+
+tumblesocks-view uses this to refresh buffers, for example.")
 (defvar tumblesocks-compose-editing-id nil
   "If editing, the ID of the post that we are editing")
 (defvar tumblesocks-compose-editing-args nil
   "If editing, which args to use while we're editing")
 
 (defun tumblesocks-compose-finish ()
+  "Actually send the new/updated post to the server."
   (interactive)
   (funcall tumblesocks-compose-finish-action)
   (let ((cc tumblesocks-compose-continuation))
@@ -41,8 +46,11 @@
 
 
 
+;;;###autoload
 (defun tumblesocks-compose-new-post (&optional continuation)
-  "Open a new buffer containing a fresh post to begin authoring."
+  "Open a new buffer containing a fresh post to begin authoring.
+
+Once you're ready to submit your post, press C-c C-c"
   (interactive)
   (pop-to-buffer "*Tumblr: New post*")
   (erase-buffer)
@@ -52,7 +60,9 @@
 
 (defun tumblesocks-compose-new-from-region (begin end &optional continuation)
   "Open a new buffer containing a fresh post, but initially
-populate it with the contents of the region."
+populate it with the contents of the region.
+
+Once you're ready to submit your post, press C-c C-c"
   (interactive "r")
   (let ((initial-body (buffer-substring begin end)))
     (tumblesocks-compose-new-post)
@@ -88,7 +98,10 @@ post buffer"
 
 
 (defun tumblesocks-compose-edit-post (post-id &optional continuation)
-  "Open a new buffer containing a fresh post to begin authoring."
+  "Open a new buffer containing a fresh post to begin authoring.
+
+Once you're ready to finish editing, press C-c C-c. You will be
+prompted for a new title and new tags."
   (interactive "sPost ID: ")
   (let* ((returned-posts
           (cdr-safe (assq 'posts

tumblesocks-user.el

@@ -1,4 +1,6 @@
 ;; tumblesocks-user.el -- higher-level functions for the tumblr api
+
+(require 'assoc)
 (require 'tumblesocks-api)
 (provide 'tumblesocks-user)
 

tumblesocks-view.el

@@ -1,13 +1,15 @@
 ;; tumblesocks-view.el -- Provide an interface to view tumblr blog posts.
 
+(require 'assoc)
 (require 'tumblesocks-api)
 (require 'tumblesocks-compose)
 (require 'shr)
 (provide 'tumblesocks-view)
 
 (defcustom tumblesocks-posts-per-page 20
   "How many posts per page to show"
-  :type 'number)
+  :type 'number
+  :group 'tumblesocks)
 
 (defvar tumblesocks-view-mode-map
   (let ((tumblesocks-view-mode-map (make-keymap)))
@@ -152,7 +154,9 @@
 (defvar tumblesocks-view-content-start nil)
 
 (define-derived-mode tumblesocks-view-mode fundamental-mode "Tumblr"
-  "Major mode for reading Tumblr blogs."
+  "Major mode for reading Tumblr blogs and posts.
+
+\\{tumblesocks-view-mode-map}"
   (make-local-variable 'tumblesocks-view-refresh-action)
   (make-local-variable 'tumblesocks-view-current-offset)
   (make-local-variable 'tumblesocks-view-content-start)
@@ -194,6 +198,9 @@
 (defun tumblesocks-view-previous-page-button-action (button)
   (tumblesocks-view-previous-page))
 (defun tumblesocks-view-previous-page ()
+  "Go back a page (into younger posts)
+
+We show `tumblesocks-posts-per-page' posts per page."
   (interactive)
   (setq tumblesocks-view-current-offset
         (max
@@ -206,6 +213,9 @@
 (defun tumblesocks-view-next-page-button-action (button)
   (tumblesocks-view-next-page))
 (defun tumblesocks-view-next-page ()
+  "Go forward a page (into older posts)
+
+We show `tumblesocks-posts-per-page' posts per page."
   (interactive)
   (setq tumblesocks-view-current-offset
          (+ tumblesocks-view-current-offset tumblesocks-posts-per-page))
@@ -216,9 +226,7 @@
 
 Blogdata should be the JSON result of a call to Tumblr's
 /blog/posts or /user/dashboard API. (We expect each post in
-blogdata to be filtered with the 'text' filter.)
-
-This function internally dispatches to other functions that are better suited to inserting each post."
+blogdata to be filtered with the 'text' filter.)"
   ;; See http://www.tumblr.com/docs/en/api/v2#posts for more
   ;; info about the post API.
   (setq tumblesocks-view-content-start (point-marker))
@@ -237,7 +245,10 @@ This function internally dispatches to other functions that are better suited to
       (put-text-property start (point) 'face font-lock-comment-face))))
 
 (defun tumblesocks-view-render-post (post &optional verbose-header)
-  "Render the post into the current buffer."
+  "Render the post into the current buffer.
+
+This function internally dispatches to other functions that are
+better suited to inserting each post."
   (let ((blog_name (cdr-safe (assq 'blog_name post)))
         (id (cdr-safe (assq 'id post)))
         (post_url (cdr-safe (assq 'post_url post)))
@@ -286,6 +297,7 @@ This function internally dispatches to other functions that are better suited to
                          post))))
 
 (defun tumblesocks-view-insert-header (&optional verbose)
+  "Draw the header for the current post, optionally being verbose."
   (let (begin end_bname)
     (setq begin (point))
     (insert blog_name ":")
@@ -433,8 +445,13 @@ This function internally dispatches to other functions that are better suited to
     (setq tumblesocks-view-refresh-action
           `(lambda () (tumblesocks-view-blog ,blogname))))) ; <-- CLOSURE HACK :p
 
+;;;###autoload
 (defun tumblesocks-view-dashboard ()
-  "View your dashboard"
+  "View the posts on your dashboard.
+
+You can browse around, edit, and delete posts from here.
+
+\\{tumblesocks-view-mode-map}"
   (interactive)
   (tumblesocks-view-prepare-buffer "Dashboard")
   (let ((dashboard-data (tumblesocks-api-user-dashboard
@@ -473,7 +490,7 @@ This function internally dispatches to other functions that are better suited to
           `(lambda () (tumblesocks-view-post ,post_id)))))
 
 (defun tumblesocks-view-render-notes (notes)
-  "Render the given notes into the given buffer"
+  "Render the given notes into the current buffer."
   (let ((start (point)))
     (insert "-- Notes:\n")
     (dolist (note (append notes nil))
@@ -517,7 +534,7 @@ This function internally dispatches to other functions that are better suited to
         (message "Unliked this post.")))))
 
 (defun tumblesocks-view-posts-tagged (tag)
-  "Search for posts with the given tag"
+  "Search for posts with the given tag."
   (interactive "sSearch for posts with tag: ")
   (tumblesocks-view-prepare-buffer
    (concat "Tag search: " tag))

tumblesocks.el

@@ -5,6 +5,10 @@
 ;; Author: gcr <gcr@sneakygcr.net>
 ;; URL: http://github.com/gcr/tumblesocks
 
+(defgroup tumblesocks nil
+  "Emacs tumblr client"
+  :group 'applications)
+
 (require 'tumblesocks-api)
 (require 'tumblesocks-user)
 (require 'tumblesocks-compose)