Wondering if error messages ought to be standardized?

5 files changed, 56 insertions, 48 deletions

diff --git a/lisp/ob-R.el b/lisp/ob-R.el
index fee1c04..127285b 100644
--- a/lisp/ob-R.el
+++ b/lisp/ob-R.el
@@ -81,8 +81,8 @@
        (list body))) "\n")))
 
 (defun org-babel-execute:R (body params)
-  "Execute a block of R code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
+  "Execute a block of R code.
+This function is called by `org-babel-execute-src-block'."
   (save-excursion
     (let* ((processed-params (org-babel-process-params params))
            (result-type (nth 3 processed-params))
@@ -211,10 +211,10 @@ write.table(main(), file=\"%s\", sep=\"\\t\", na=\"nil\",row.names=%s, col.names
 
 (defun org-babel-R-evaluate
   (session body result-type column-names-p row-names-p)
-  "Pass BODY to the R process in SESSION.  If RESULT-TYPE equals
-'output then return a list of the outputs of the statements in
-BODY, if RESULT-TYPE equals 'value then return the value of the
-last statement in BODY, as elisp."
+  "Pass BODY to the R process in SESSION.
+If RESULT-TYPE equals 'output then return a list of the outputs
+of the statements in BODY, if RESULT-TYPE equals 'value then
+return the value of the last statement in BODY, as elisp."
   (if (not session)
       ;; external process evaluation
       (case result-type
@@ -266,13 +266,11 @@ last statement in BODY, as elisp."
 		  (inferior-ess-send-input)))) 2) "\n")))))
 
 (defun org-babel-R-process-value-result (result column-names-p)
-  "R-specific processing of return value prior to return to
-org-babel.  Insert hline if column names in output have been
-requested."
+  "R-specific processing of return value.
+Insert hline if column names in output have been requested."
   (if column-names-p
       (cons (car result) (cons 'hline (cdr result)))
     result))
-  
 
 (provide 'ob-R)
 
diff --git a/lisp/ob-asymptote.el b/lisp/ob-asymptote.el
index 8399e5a..3a2158f 100644
--- a/lisp/ob-asymptote.el
+++ b/lisp/ob-asymptote.el
@@ -53,7 +53,7 @@
 
 (defvar org-babel-default-header-args:asymptote
   '((:results . "file") (:exports . "results"))
-  "Default arguments to use when evaluating a asymptote source block.")
+  "Default arguments when evaluating an Asymptote source block.")
 
 (defun org-babel-expand-body:asymptote (body params &optional processed-params)
   "Expand BODY according to PARAMS, return the expanded body."
@@ -63,8 +63,8 @@
 	    "\n" body "\n")))
 
 (defun org-babel-execute:asymptote (body params)
-  "Execute a block of Asymptote code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
+  "Execute a block of Asymptote code.
+This function is called by `org-babel-execute-src-block'."
   (let* ((processed-params (org-babel-process-params params))
          (result-params (split-string (or (cdr (assoc :results params)) "")))
          (out-file (cdr (assoc :file params)))
@@ -85,12 +85,14 @@ called by `org-babel-execute-src-block'."
     out-file))
 
 (defun org-babel-prep-session:asymptote (session params)
-  "Prepare a session named SESSION according to PARAMS."
+  "Return an error if the :session header argument is set.
+Asymptote does not support sessions"
   (error "Asymptote does not support sessions"))
 
 (defun org-babel-asymptote-var-to-asymptote (pair)
-  "Convert an elisp val into a string of asymptote code specifying a var
-of the same value."
+  "Convert an elisp value into an Asymptote variable.
+The elisp value PAIR is converted into Asymptote code specifying
+a variable of the same value."
   (let ((var (car pair))
         (val (if (symbolp (cdr pair))
                  (symbol-name (cdr pair))
@@ -134,10 +136,10 @@ Empty cells are ignored."
      (org-combine-plists '(:hline nil :sep "," :tstart "{" :tend "}") params))))
 
 (defun org-babel-asymptote-define-type (data)
-  "Determine type of DATA. DATA is a list. Type symbol is
-returned as 'symbol. The type is usually the type of the first
-atom encountered, except for arrays of int where every cell must
-be of int type."
+  "Determine type of DATA.
+DATA is a list. Type symbol is returned as 'symbol. The type is
+usually the type of the first atom encountered, except for arrays
+of int, where every cell must be of int type."
   (labels ((anything-but-int (el)
                              (cond
                               ((null el) nil)
diff --git a/lisp/ob-clojure.el b/lisp/ob-clojure.el
index 58a1c2a..7f1a6e5 100644
--- a/lisp/ob-clojure.el
+++ b/lisp/ob-clojure.el
@@ -116,8 +116,9 @@
          "clojure.main"))))))
 
 (defun org-babel-clojure-table-or-string (results)
-  "If RESULTS looks like a table, then convert them into an
-Emacs-lisp table, otherwise return the results as a string."
+  "Convert RESULTS to an elisp value.
+If RESULTS looks like a table, then convert to an Emacs-lisp
+table, otherwise return the results as a string."
   (org-babel-read
    (if (string-match "^\\[.+\\]$" results)
        (org-babel-read
@@ -130,14 +131,15 @@ Emacs-lisp table, otherwise return the results as a string."
      results)))
 
 (defun org-babel-clojure-var-to-clojure (var)
-  "Convert an elisp var into a string of clojure source code
-specifying a var of the same value."
+  "Convert an elisp value into a clojure variable.
+The elisp value VAR is converted into a string of clojure source
+code specifying a variable of the same value."
   (if (listp var)
       (format "'%s" var)
     (format "%S" var)))
 
 (defun org-babel-clojure-build-full-form (body vars)
-  "Construct a clojure let form with vars as the let vars."
+  "Construct a clojure let form with VARS as the let variables."
   (let ((vars-forms
 	 (mapconcat ;; define any variables
 	  (lambda (pair)
@@ -179,7 +181,8 @@ specifying a var of the same value."
   (cdr (assoc session org-babel-clojure-buffers)))
 
 (defun org-babel-clojure-initiate-session-by-key (&optional session)
-  "If there is not a current inferior-process-buffer in SESSION
+  "Initiate a clojure session in an inferior-process-buffer.
+If there is not a current inferior-process-buffer in SESSION
 then create one.  Return the initialized session."
   (save-window-excursion
     (let* ((session (if session
@@ -209,15 +212,15 @@ then create one.  Return the initialized session."
       session)))
 
 (defun org-babel-clojure-initiate-session (&optional session params)
-  "Return the slime-clojure repl buffer bound to this session
-or nil if \"none\" is specified."
+  "Return the slime-clojure repl buffer bound to SESSION.
+Returns nil if \"none\" is specified."
   (require 'slime) (require 'swank-clojure)
   (unless (and (stringp session) (string= session "none"))
     (org-babel-clojure-session-buffer
      (org-babel-clojure-initiate-session-by-key session))))
 
 (defun org-babel-clojure-session-connected-hook ()
-  "Finish setting up the bindings of org-babel session to a slime-clojure repl."
+  "Finish  binding an org-babel session to a slime-clojure repl."
   (let ((pending-session (pop org-babel-clojure-pending-sessions)))
     (when pending-session
       (save-excursion
@@ -279,10 +282,10 @@ repl buffer."
 	(org-babel-clojure-table-or-string (car results)))))))
 
 (defun org-babel-clojure-evaluate (buffer body &optional result-type)
-  "Pass BODY to the Clojure process in BUFFER.  If RESULT-TYPE equals
-'output then return a list of the outputs of the statements in
-BODY, if RESULT-TYPE equals 'value then return the value of the
-last statement in BODY, as elisp."
+  "Pass BODY to the Clojure process in BUFFER.
+If RESULT-TYPE equals 'output then return a list of the outputs
+of the statements in BODY, if RESULT-TYPE equals 'value then
+return the value of the last statement in BODY as elisp."
   (if buffer
       (org-babel-clojure-evaluate-session buffer body result-type)
     (org-babel-clojure-evaluate-external-process buffer body result-type)))
@@ -293,7 +296,7 @@ last statement in BODY, as elisp."
    body (nth 1 (or processed-params (org-babel-process-params params)))))
 
 (defun org-babel-execute:clojure (body params)
-  "Execute a block of Clojure code with org-babel."
+  "Execute a block of Clojure code."
   (require 'slime) (require 'swank-clojure)
   (let* ((processed-params (org-babel-process-params params))
          (body (org-babel-expand-body:clojure body params processed-params))
diff --git a/lisp/ob-comint.el b/lisp/ob-comint.el
index 6c13bb6..978d55e 100644
--- a/lisp/ob-comint.el
+++ b/lisp/ob-comint.el
@@ -41,8 +41,9 @@
     (and buffer (buffer-live-p buffer) (get-buffer-process buffer) buffer)))
 
 (defmacro org-babel-comint-in-buffer (buffer &rest body)
-  "Check BUFFER with `org-babel-comint-buffer-livep' then execute
-body inside the protection of `save-window-excursion' and
+  "Check BUFFER and execute BODY.
+BUFFER is checked with `org-babel-comint-buffer-livep'.  BODY is
+executed inside the protection of `save-window-excursion' and
 `save-match-data'."
   (declare (indent 1))
   `(save-excursion
@@ -53,11 +54,12 @@ body inside the protection of `save-window-excursion' and
        ,@body)))
 
 (defmacro org-babel-comint-with-output (meta &rest body)
-  "Evaluate BODY in BUFFER, wait until EOE-INDICATOR appears in
-output, then return all process output.  If REMOVE-ECHO and
-FULL-BODY are present and non-nil, then strip echo'd body from
-the returned output.  META should be a list containing the
-following where the last two elements are optional.
+  "Evaluate BODY in BUFFER and return process output.
+Will wait until EOE-INDICATOR appears in the output, then return
+all process output.  If REMOVE-ECHO and FULL-BODY are present and
+non-nil, then strip echo'd body from the returned output.  META
+should be a list containing the following where the last two
+elements are optional.
 
  (BUFFER EOE-INDICATOR REMOVE-ECHO FULL-BODY)
 
@@ -113,7 +115,8 @@ or user `keyboard-quit' during execution of body."
 	 (split-string string-buffer comint-prompt-regexp)))))
 
 (defun org-babel-comint-input-command (buffer cmd)
-  "Pass CMD to BUFFER  The input will not be echoed."
+  "Pass CMD to BUFFER.
+The input will not be echoed."
   (org-babel-comint-in-buffer buffer
     (goto-char (process-mark (get-buffer-process buffer)))
     (insert cmd)
@@ -121,9 +124,9 @@ or user `keyboard-quit' during execution of body."
     (org-babel-comint-wait-for-output buffer)))
 
 (defun org-babel-comint-wait-for-output (buffer)
-  "Wait until output arrives from BUFFER.  Note: this is only
-safe when waiting for the result of a single statement (not large
-blocks of code)."
+  "Wait until output arrives from BUFFER.
+Note: this is only safe when waiting for the result of a single
+statement (not large blocks of code)."
   (org-babel-comint-in-buffer buffer
     (while (progn
              (goto-char comint-last-input-end)
diff --git a/lisp/ob-css.el b/lisp/ob-css.el
index c73bbef..a6dce84 100644
--- a/lisp/ob-css.el
+++ b/lisp/ob-css.el
@@ -36,11 +36,13 @@
   "Expand BODY according to PARAMS, return the expanded body." body)
 
 (defun org-babel-execute:css (body params)
-  "Execute a block of CSS code with org-babel.  This function is
-called by `org-babel-execute-src-block'." body)
+  "Execute a block of CSS code.
+This function is called by `org-babel-execute-src-block'."
+ body)
 
 (defun org-babel-prep-session:css (session params)
-  "Prepare SESSION according to the header arguments specified in PARAMS."
+  "Return an error if the :session header argument is set.
+CSS does not support sessions."
   (error "CSS sessions are nonsensical"))
 
 (provide 'ob-css)