Merge branch 'master' of git+ssh://repo.or.cz/srv/git/org-mode

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)
 

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)

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))

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)

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)

lisp/ob-ditaa.el

@@ -41,15 +41,15 @@
 
 (defvar org-babel-default-header-args:ditaa
   '((:results . "file") (:exports . "results"))
-  "Default arguments to use when evaluating a ditaa source block.")
+  "Default arguments for evaluating a ditaa source block.")
 
 (defun org-babel-expand-body:ditaa (body params &optional processed-params)
   "Expand BODY according to PARAMS, return the expanded body." body)
 
 (defvar org-ditaa-jar-path)
 (defun org-babel-execute:ditaa (body params)
-  "Execute a block of Ditaa code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
+  "Execute a block of Ditaa code with org-babel.
+This function is called by `org-babel-execute-src-block'."
   (let ((result-params (split-string (or (cdr (assoc :results params)) "")))
         (out-file (cdr (assoc :file params)))
         (cmdline (cdr (assoc :cmdline params)))
@@ -62,8 +62,7 @@ called by `org-babel-execute-src-block'."
     out-file))
 
 (defun org-babel-prep-session:ditaa (session params)
-  "This function does nothing as ditaa does not support
-sessions."
+  "Return an error because ditaa does not support sessions."
   (error "Ditaa does not support sessions"))
 
 (provide 'ob-ditaa)

lisp/ob-dot.el

@@ -50,8 +50,8 @@
   "Expand BODY according to PARAMS, return the expanded body." body)
 
 (defun org-babel-execute:dot (body params)
-  "Execute a block of Dot code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
+  "Execute a block of Dot code with org-babel.
+This function is called by `org-babel-execute-src-block'."
   (let ((result-params (split-string (or (cdr (assoc :results params)) "")))
         (out-file (cdr (assoc :file params)))
         (cmdline (cdr (assoc :cmdline params)))
@@ -62,7 +62,7 @@ called by `org-babel-execute-src-block'."
     out-file))
 
 (defun org-babel-prep-session:dot (session params)
-  "Prepare SESSION according to the contents of PARAMS."
+  "Return an error because Dot does not support sessions."
   (error "Dot does not support sessions"))
 
 (provide 'ob-dot)

lisp/ob-emacs-lisp.el

@@ -31,7 +31,7 @@
 
 (defvar org-babel-default-header-args:emacs-lisp
   '((:hlines . "yes") (:colnames . "no"))
-  "Default arguments to use when evaluating an emacs-lisp source block.")
+  "Default arguments for evaluating an emacs-lisp source block.")
 
 (declare-function org-babel-comint-with-output "ob-comint" (&rest body))
 (declare-function org-babel-comint-buffer-livep "ob-comint" (buffer))
@@ -57,7 +57,7 @@
 	(concat "(pp " body ")") body)))
 
 (defun org-babel-execute:emacs-lisp (body params)
-  "Execute a block of emacs-lisp code with org-babel."
+  "Execute a block of emacs-lisp code with Babel."
   (save-window-excursion
     (let ((processed-params (org-babel-process-params params)))
       (org-babel-reassemble-table

lisp/ob-eval.el

@@ -32,18 +32,18 @@
 (eval-when-compile (require 'cl))
 
 (defun org-babel-eval-error-notify (exit-code stderr)
-  "Open a buffer containing information from STDERR with a
-message about the value of EXIT-CODE."
+  "Open a buffer to display STDERR and a message with the value of EXIT-CODE."
   (let ((buf (get-buffer-create "*Org-Babel Error Output*")))
     (with-current-buffer buf
       (goto-char (point-max))
       (save-excursion (insert stderr)))
     (display-buffer buf))
-  (message "Babel evaluation exited with code %d" exit-code))
+  (message "Babel evaluation exited with code %S" exit-code))
 
 (defun org-babel-eval (cmd body)
-  "Run CMD on BODY, if CMD succeeds then return it's results,
-otherwise display STDERR with `org-babel-eval-error-notify'."
+  "Run CMD on BODY.
+If CMD succeeds then return it's results, otherwise display
+STDERR with `org-babel-eval-error-notify'."
   (let ((err-buff (get-buffer-create "*Org-Babel Error*")) exit-code)
     (with-current-buffer err-buff (erase-buffer))
     (with-temp-buffer
@@ -51,7 +51,7 @@ otherwise display STDERR with `org-babel-eval-error-notify'."
       (setq exit-code
 	    (org-babel-shell-command-on-region
 	     (point-min) (point-max) cmd t 'replace err-buff))
-      (if (> exit-code 0)
+      (if (or (not (numberp exit-code)) (> exit-code 0))
 	  (progn
 	    (with-current-buffer err-buff
 	      (org-babel-eval-error-notify exit-code (buffer-string)))
@@ -67,7 +67,7 @@ otherwise display STDERR with `org-babel-eval-error-notify'."
 (defun org-babel-shell-command-on-region (start end command
 				      &optional output-buffer replace
 				      error-buffer display-error-buffer)
-  "Execute string COMMAND in inferior shell with region as input.
+  "Execute COMMAND in an inferior shell with region as input.
 
 Fixes bugs in the emacs 23.1.1 version of `shell-command-on-region'
 

lisp/ob-exp.el

@@ -56,7 +56,8 @@ process."
 (put 'org-export-babel-evaluate 'safe-local-variable (lambda (x) (eq x nil)))
 
 (defvar org-babel-function-def-export-keyword "function"
-  "When exporting a source block function, this keyword will
+  "The keyword to substitute for the source name line on export.
+When exporting a source block function, this keyword will
 appear in the exported version in the place of source name
 line. A source block is considered to be a source block function
 if the source name is present and is followed by a parenthesized
@@ -70,14 +71,16 @@ whitespace. An example is the following which generates n random
 #+end_src")
 
 (defvar org-babel-function-def-export-indent 4
-  "When exporting a source block function, the block contents
-will be indented by this many characters. See
+  "Number of characters to indent a source block on export.
+When exporting a source block function, the block contents will
+be indented by this many characters. See
 `org-babel-function-def-export-name' for the definition of a
 source block function.")
 
 (defun org-babel-exp-src-blocks (body &rest headers)
-  "Process src block for export.  Depending on the 'export'
-headers argument in replace the source code block with...
+  "Process source block for export.
+Depending on the 'export' headers argument in replace the source
+code block with...
 
 both ---- display the code and the results
 
@@ -104,7 +107,7 @@ none ----- do not display either code or results upon export"
       (org-babel-exp-do-export info 'block))))
 
 (defun org-babel-exp-inline-src-blocks (start end)
-  "Process inline src blocks between START and END for export.
+  "Process inline source blocks between START and END for export.
 See `org-babel-exp-src-blocks' for export options, currently the
 options and are taken from `org-babel-default-inline-header-args'."
   (interactive)
@@ -130,9 +133,9 @@ options and are taken from `org-babel-default-inline-header-args'."
 	(replace-match replacement t t nil 1)))))
 
 (defun org-exp-res/src-name-cleanup ()
-  "Cleanup leftover #+results and #+srcname lines as part of the
-org export cycle.  This should only be called after all block
-processing has taken place."
+  "Clean up #+results and #+srcname lines for export.
+This function should only be called after all block processing
+has taken place."
   (interactive)
   (save-excursion
     (goto-char (point-min))
@@ -145,8 +148,9 @@ processing has taken place."
        (progn (end-of-line) (+ 1 (point)))))))
 
 (defun org-babel-in-example-or-verbatim ()
-  "Return true if the point is currently in an escaped portion of
-an org-mode buffer code which should be treated as normal
+  "Return true if point is in example or verbatim code.
+Example and verbatim code include escaped portions of
+an org-mode buffer code that should be treated as normal
 org-mode text."
   (or (org-in-indented-comment-line) 
       (save-excursion
@@ -156,7 +160,7 @@ org-mode text."
       (org-in-regexps-block-p "^[ \t]*#\\+begin_src" "^[ \t]*#\\+end_src")))
 
 (defun org-babel-exp-lob-one-liners (start end)
-  "Process #+lob (Library of Babel) calls between START and END for export.
+  "Process Library of Babel calls between START and END for export.
 See `org-babel-exp-src-blocks' for export options. Currently the
 options are taken from `org-babel-default-header-args'."
   (interactive)
@@ -183,8 +187,8 @@ options are taken from `org-babel-default-header-args'."
 	(replace-match replacement t t)))))
 
 (defun org-babel-exp-do-export (info type)
-  "Return a string containing the exported content of the current
-code block respecting the value of the :exports header argument."
+  "Return a string with the exported content of a code block.
+The function respects the value of the :exports header argument."
   (flet ((silently () (let ((session (cdr (assoc :session (nth 2 info)))))
 			(when (and session
 				   (not (equal "none" session))
@@ -201,10 +205,10 @@ code block respecting the value of the :exports header argument."
 
 (defvar backend)
 (defun org-babel-exp-code (info type)
-  "Return the code the current code block in a manner suitable
-for exportation by org-mode.  This function is called by
-`org-babel-exp-do-export'.  The code block will not be
-evaluated."
+  "Prepare and return code in the current code block for export.
+Code is prepared in a manner suitable for exportat by
+org-mode.  This function is called by `org-babel-exp-do-export'.
+The code block is not evaluated."
   (let ((lang (nth 0 info))
         (body (nth 1 info))
         (switches (nth 3 info))
@@ -238,11 +242,11 @@ evaluated."
 	  ((format ": %s\n" call-line))))))))
 
 (defun org-babel-exp-results (info type &optional silent)
-  "Return the results of the current code block in a manner
-suitable for exportation by org-mode.  This function is called by
-`org-babel-exp-do-export'.  The code block will be evaluated.
-Optional argument SILENT can be used to inhibit insertion of
-results into the buffer."
+  "Evaluate and return the results of the current code block for export.
+Results are prepared in a manner suitable for export by org-mode.
+This function is called by `org-babel-exp-do-export'.  The code
+block will be evaluated.  Optional argument SILENT can be used to
+inhibit insertion of results into the buffer."
   (if org-export-babel-evaluate
       (let ((lang (nth 0 info))
 	    (body (nth 1 info))

lisp/ob-gnuplot.el

@@ -58,8 +58,8 @@
 (defvar org-babel-gnuplot-timestamp-fmt nil)
 
 (defun org-babel-gnuplot-process-vars (params)
-  "Extract variables from PARAMS and process the variables
-dumping all vectors into files and returning an association list
+  "Extract variables from PARAMS and process the variables.
+Dumps all vectors into files and returns an association list
 of variable names and the related value to be used in the gnuplot
 code."
   (mapcar
@@ -130,8 +130,8 @@ code."
       body)))
 
 (defun org-babel-execute:gnuplot (body params)
-  "Execute a block of Gnuplot code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
+  "Execute a block of Gnuplot code.
+This function is called by `org-babel-execute-src-block'."
   (require 'gnuplot)
   (let ((session (cdr (assoc :session params)))
         (result-type (cdr (assoc :results params)))
@@ -157,7 +157,7 @@ called by `org-babel-execute-src-block'."
         out-file))))
 
 (defun org-babel-prep-session:gnuplot (session params)
-  "Prepare SESSION according to the header arguments specified in PARAMS."
+  "Prepare SESSION according to the header arguments in PARAMS."
   (let* ((session (org-babel-gnuplot-initiate-session session))
          (vars (org-babel-ref-variables params))
          (var-lines (mapcar
@@ -182,7 +182,8 @@ called by `org-babel-execute-src-block'."
 
 (defvar gnuplot-buffer)
 (defun org-babel-gnuplot-initiate-session (&optional session params)
-  "If there is not a current inferior-process-buffer in SESSION
+  "Initiate a gnuplot session.
+If there is not a current inferior-process-buffer in SESSION
 then create one.  Return the initialized session.  The current
 `gnuplot-mode' doesn't provide support for multiple sessions."
   (require 'gnuplot)
@@ -192,13 +193,13 @@ then create one.  Return the initialized session.  The current
       gnuplot-buffer)))
 
 (defun org-babel-gnuplot-quote-timestamp-field (s)
-  "Convert field S from timestamp to Unix time and export to gnuplot."
+  "Convert S from timestamp to Unix time and export to gnuplot."
   (format-time-string org-babel-gnuplot-timestamp-fmt (org-time-string-to-time s)))
 
 (defvar org-table-number-regexp)
 (defvar org-ts-regexp3)
 (defun org-babel-gnuplot-quote-tsv-field (s)
-  "Quote field S for export to gnuplot."
+  "Quote S for export to gnuplot."
   (unless (stringp s)
     (setq s (format "%s" s)))
   (if (string-match org-table-number-regexp s) s

lisp/ob-haskell.el

@@ -70,7 +70,7 @@
       vars "\n") "\n" body "\n")))
 
 (defun org-babel-execute:haskell (body params)
-  "Execute a block of Haskell code with org-babel."
+  "Execute a block of Haskell code."
   (let* ((processed-params (org-babel-process-params params))
          (session (nth 0 processed-params))
          (vars (nth 1 processed-params))
@@ -103,7 +103,8 @@
     string))
 
 (defun org-babel-haskell-initiate-session (&optional session params)
-  "If there is not a current inferior-process-buffer in SESSION
+  "Initiate a haskell session.
+If there is not a current inferior-process-buffer in SESSION
 then create one.  Return the initialized session."
   (require 'inf-haskell)
   (or (get-buffer "*haskell*")
@@ -123,7 +124,7 @@ then create one.  Return the initialized session."
 
 (defun org-babel-prep-session:haskell
   (session params &optional processed-params)
-  "Prepare SESSION according to the header arguments specified in PARAMS."
+  "Prepare SESSION according to the header arguments in PARAMS."
   (save-window-excursion
     (let ((pp (or processed-params (org-babel-process-params params)))
 	  (buffer (org-babel-haskell-initiate-session session)))
@@ -138,7 +139,8 @@ then create one.  Return the initialized session."
       (current-buffer))))
 
 (defun org-babel-haskell-table-or-string (results)
-  "If the results look like a table, then convert them into an
+  "Convert RESULTS to an Emacs-lisp table or string.
+If RESULTS look like a table, then convert them into an
 Emacs-lisp table, otherwise return the results as a string."
   (org-babel-read
    (if (and (stringp results) (string-match "^\\[.+\\]$" results))
@@ -152,21 +154,22 @@ Emacs-lisp table, otherwise return the results as a string."
      results)))
 
 (defun org-babel-haskell-var-to-haskell (var)
-  "Convert an elisp var into a string of haskell source code
-specifying a var of the same value."
+  "Convert an elisp value VAR into a haskell variable.
+The elisp VAR is converted to a string of haskell source code
+specifying a variable of the same value."
   (if (listp var)
       (concat "[" (mapconcat #'org-babel-haskell-var-to-haskell var ", ") "]")
     (format "%S" var)))
 
 (defvar org-src-preserve-indentation)
 (defun org-babel-haskell-export-to-lhs (&optional arg)
-  "Export to a .lhs file with all haskell code blocks escaped
-appropriately.  When called with a prefix argument the resulting
+  "Export to a .lhs file with all haskell code blocks escaped.
+When called with a prefix argument the resulting
 .lhs file will be exported to a .tex file.  This function will
 create two new files, base-name.lhs and base-name.tex where
 base-name is the name of the current org-mode file.
 
-Note that all standard org-babel literate programming
+Note that all standard Babel literate programming
 constructs (header arguments, no-web syntax etc...) are ignored."
   (interactive "P")
   (let* ((contents (buffer-string))

lisp/ob-keys.el

@@ -33,20 +33,17 @@
 (require 'ob)
 
 (defvar org-babel-key-prefix "\C-c\C-v"
-  "The `org-babel-key-prefix' variable holds the key prefix
-behind which all org-babel interactive key-binding are placed.
+  "The key prefix for Babel interactive key-bindings.
 See `org-babel-key-bindings' for the list of interactive babel
 functions which are assigned key bindings, and see
 `org-babel-map' for the actual babel keymap.")
 
 (defvar org-babel-map (make-sparse-keymap)
-  "The keymap holding key bindings for interactive org-babel
-functions.")
+  "The keymap for interactive Babel functions.")
 
 ;;;###autoload
 (defun org-babel-describe-bindings ()
-  "Describe all key binding placed behind the
-`org-babel-key-prefix' prefix."
+  "Describe all keybindings behind `org-babel-key-prefix'."
   (interactive)
   (describe-bindings org-babel-key-prefix))
 
@@ -79,8 +76,8 @@ functions.")
     ("\C-a" . org-babel-sha1-hash)
     ("a" . org-babel-sha1-hash)
     ("h" . org-babel-describe-bindings))
-  "Alist associating key bindings with interactive Org-babel
-functions.  This list associates interactive org-babel functions
+  "Alist of key bindings and interactive Babel functions.
+This list associates interactive Babel functions
 with keys.  Each element of this list will add an entry to the
 `org-babel-map' using the letter key which is the `car' of the
 a-list placed behind the generic `org-babel-key-prefix'.")

lisp/ob-latex.el

@@ -42,7 +42,7 @@
 
 (defvar org-babel-default-header-args:latex
   '((:results . "latex") (:exports . "results"))
-  "Default arguments to use when evaluating a latex source block.")
+  "Default arguments to use when evaluating a LaTeX source block.")
 
 (defun org-babel-expand-body:latex (body params &optional processed-params)
   "Expand BODY according to PARAMS, return the expanded body."
@@ -58,8 +58,8 @@
 (defvar org-format-latex-options)
 (defvar org-export-latex-packages-alist)
 (defun org-babel-execute:latex (body params)
-  "Execute a block of Latex code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
+  "Execute a block of Latex code with Babel.
+This function is called by `org-babel-execute-src-block'."
   (setq body (org-babel-expand-body:latex body params))
   (if (cdr (assoc :file params))
       (let ((out-file (cdr (assoc :file params)))
@@ -89,8 +89,8 @@ called by `org-babel-execute-src-block'."
 (defvar org-export-latex-packages-alist)
 (defvar org-export-latex-default-packages-alist)
 (defun org-babel-latex-body-to-tex-file (tex-file body &optional height width)
-  "Place the contents of BODY into TEX-FILE. Extracted from
-`org-create-formula-image' in org.el."
+  "Place the contents of BODY into TEX-FILE.
+Extracted from `org-create-formula-image' in org.el."
   (with-temp-file tex-file
     (insert (org-splice-latex-header
 	       org-format-latex-header
@@ -114,8 +114,8 @@ called by `org-babel-execute-src-block'."
 (defvar org-latex-to-pdf-process)
 (defvar org-export-pdf-remove-logfiles)
 (defun org-babel-latex-tex-to-pdf (tex-file)
-  "Generate a pdf according to the contents TEX-FILE.  Extracted
-from `org-export-as-pdf' in org-latex.el."
+  "Generate a pdf file according to the contents TEX-FILE.
+Extracted from `org-export-as-pdf' in org-latex.el."
   (let* ((wconfig (current-window-configuration))
          (default-directory (file-name-directory tex-file))
          (base (file-name-sans-extension tex-file))
@@ -148,8 +148,8 @@ from `org-export-as-pdf' in org-latex.el."
       pdffile)))
 
 (defun org-babel-prep-session:latex (session params)
-  "Create a session named SESSION according to PARAMS."
-  (error "Latex does not support sessions"))
+  "Return an error because LaTeX doesn't support sesstions."
+  (error "LaTeX does not support sessions"))
 
 (provide 'ob-latex)
 

lisp/ob-lob.el

@@ -33,12 +33,13 @@
 (require 'ob-table)
 
 (defvar org-babel-library-of-babel nil
-  "Library of source-code blocks.  This is an association list.
-Populate the library by adding files to `org-babel-lob-files'.")
+  "Library of source-code blocks.
+This is an association list.  Populate the library by adding
+files to `org-babel-lob-files'.")
 
 (defcustom org-babel-lob-files '()
-  "Files used to populate the `org-babel-library-of-babel'.  To
-add files to this list use the `org-babel-lob-ingest' command."
+  "Files used to populate the `org-babel-library-of-babel'.
+To add files to this list use the `org-babel-lob-ingest' command."
   :group 'org-babel
   :type 'list)
 
@@ -55,23 +56,22 @@ add files to this list use the `org-babel-lob-ingest' command."
                     (assq-delete-all source-name org-babel-library-of-babel)))))))
 
 (defconst org-babel-lob-call-aliases '("lob" "call")
-  "These can be used interchangeably to call a source block
-  function. If you change the value of this variable then your
-  files may become unusable by other org-babel users, and vice
-  versa.")
+  "Aliases to call a source block function.
+If you change the value of this variable then your files may
+  become unusable by other org-babel users, and vice versa.")
 
 (defconst org-babel-lob-one-liner-regexp
   (concat "^\\([ \t]*\\)#\\+\\(?:"
 	  (mapconcat #'regexp-quote org-babel-lob-call-aliases "\\|")
 	  "\\):[ \t]+\\([^\(\)\n]+\\)\(\\([^\n]*\\)\)[ \t]*\\([^\n]*\\)")
-  "Regexp to match calls to predefined source block functions")
+  "Regexp to match calls to predefined source block functions.")
 
 ;; functions for executing lob one-liners
 ;;;###autoload
 (defun org-babel-lob-execute-maybe ()
-  "Detect if this is context for a org-babel Library Of Babel
-src-block and if so then run the appropriate source block from
-the Library."
+  "Execute a Library of Babel source block, if appropriate.
+Detect if this is context for a Library Of Babel source block and
+if so then run the appropriate source block from the Library."
   (interactive)
   (let ((info (org-babel-lob-get-info)))
     (if (nth 0 info) (progn (org-babel-lob-execute info) t) nil)))
@@ -80,8 +80,7 @@ the Library."
 
 ;;;###autoload
 (defun org-babel-lob-get-info ()
-  "Return the function call supplied on the current Library of
-Babel line as a string.
+  "Return a Library of Babel function call as a string.
 
 This function is analogous to org-babel-get-src-block-name. For
 both functions, after they are called, (match-string 1) matches

lisp/ob-mscgen.el

@@ -66,10 +66,10 @@
   "Expand BODY according to PARAMS, return the expanded body." body)
 
 (defun org-babel-execute:mscgen (body params)
-  "Execute a block of Mscgen code with org-babel.  This function
-is called by `org-babel-execute-src-block'.  Default filetype is
-png. Modify by setting :filetype parameter to mscgen supported
-formats."
+  "Execute a block of Mscgen code with Babel.
+This function is called by `org-babel-execute-src-block'.
+Default filetype is png. Modify by setting :filetype parameter to
+mscgen supported formats."
   (let* ((out-file (or (cdr (assoc :file params)) "output.png" ))
          (filetype (or (cdr (assoc :filetype params)) "png" )))
     (unless (cdr (assoc :file params))
@@ -79,7 +79,7 @@ ERROR: no output file specified. Add \":file name.png\" to the src header"))
     out-file))
 
 (defun org-babel-prep-session:mscgen (session params)
-  "Prepare SESSION according to PARAMS."
+  "Raise an error because Mscgen doesn't support sessions."
   (error "Mscgen does not support sessions"))
 
 (provide 'ob-mscgen)

lisp/ob-ocaml.el

@@ -59,7 +59,7 @@
       vars "\n") "\n" body "\n")))
 
 (defun org-babel-execute:ocaml (body params)
-  "Execute a block of Ocaml code with org-babel."
+  "Execute a block of Ocaml code with Babel."
   (let* ((processed-params (org-babel-process-params params))
          (vars (nth 1 processed-params))
          (full-body (org-babel-expand-body:ocaml body params processed-params))
@@ -78,7 +78,7 @@
 
 (defvar tuareg-interactive-buffer-name)
 (defun org-babel-prep-session:ocaml (session params)
-  "Prepare SESSION according to the header arguments specified in PARAMS."
+  "Prepare SESSION according to the header arguments in PARAMS."
   (require 'tuareg)
   (let ((tuareg-interactive-buffer-name (if (and (not (string= session "none"))
                                                  (not (string= session "default"))
@@ -89,8 +89,8 @@
                            (get-buffer tuareg-interactive-buffer-name))))
 
 (defun org-babel-ocaml-parse-output (output)
-  "Parse OUTPUT where OUTPUT is string output from an ocaml
-process."
+  "Parse OUTPUT.
+OUTPUT is string output from an ocaml process."
   (let ((regexp "%s = \\(.+\\)$"))
     (cond
      ((string-match (format regexp "string") output)
@@ -105,7 +105,8 @@ process."
      (t (message "don't recognize type of %s" output) output))))
 
 (defun org-babel-ocaml-read-list (results)
-  "If the results look like a table, then convert them into an
+  "Convert RESULTS into an elisp table or string.
+If the results look like a table, then convert them into an
 Emacs-lisp table, otherwise return the results as a string."
   (org-babel-read
    (if (and (stringp results) (string-match "^\\[.+\\]$" results))
@@ -118,7 +119,8 @@ Emacs-lisp table, otherwise return the results as a string."
      results)))
 
 (defun org-babel-ocaml-read-array (results)
-  "If the results look like a table, then convert them into an
+  "Convert RESULTS into an elisp table or string.
+If the results look like a table, then convert them into an
 Emacs-lisp table, otherwise return the results as a string."
   (org-babel-read
    (if (and (stringp results) (string-match "^\\[.+\\]$" results))

lisp/ob-octave.el

@@ -43,9 +43,9 @@
 (defvar org-babel-default-header-args:octave '())
 
 (defvar org-babel-matlab-shell-command "matlab -nosplash"
-  "Shell command to use to run matlab as an external process.")
+  "Shell command to run matlab as an external process.")
 (defvar org-babel-octave-shell-command "octave -q"
-  "Shell command to use to run octave as an external process.")
+  "Shell command to run octave as an external process.")
 
 (defun org-babel-expand-body:matlab (body params &optional processed-params)
   "Expand BODY according to PARAMS, return the expanded body."
@@ -62,9 +62,9 @@
       vars "\n") "\n" body "\n")))
 
 (defvar org-babel-matlab-with-emacs-link nil
-  "If non-nil use matlab-shell-run-region for session
-  evaluation. This will use EmacsLink if (matlab-with-emacs-link)
-  evaluates to a non-nil value.")
+  "If non-nil use matlab-shell-run-region for session evaluation.
+  This will use EmacsLink if (matlab-with-emacs-link) evaluates
+  to a non-nil value.")
 
 (defvar org-babel-matlab-emacs-link-wrapper-method
    "%s
@@ -84,11 +84,11 @@ end")
 (defvar org-babel-octave-eoe-output "ans = org_babel_eoe")
 
 (defun org-babel-execute:matlab (body params)
-  "Execute a block of matlab code with org-babel."
+  "Execute a block of matlab code with Babel."
   (require 'matlab)
   (org-babel-execute:octave body params 'matlab))
 (defun org-babel-execute:octave (body params &optional matlabp)
-  "Execute a block of octave code with org-babel."
+  "Execute a block of octave code with Babel."
   (let* ((processed-params (org-babel-process-params params))
          (session
 	  (funcall (intern (format "org-babel-%s-initiate-session"
@@ -115,7 +115,7 @@ end")
   (require 'matlab)
   (org-babel-prep-session:octave session params 'matlab))
 (defun org-babel-octave-var-to-octave (var)
-  "Convert an emacs-lisp variable into an octave variable.
+  "Convert an emacs-lisp value into an octave variable.
 Converts an emacs-lisp variable into a string of octave code
 specifying a variable of the same value."
   (if (listp var)
@@ -139,15 +139,15 @@ specifying a variable of the same value."
     session))
 
 (defun org-babel-matlab-initiate-session (&optional session params)
-  "Create a matlab inferior process buffer.  If there is not a
-current inferior-process-buffer in SESSION then create. Return
-the initialized session."
+  "Create a matlab inferior process buffer.
+If there is not a current inferior-process-buffer in SESSION then
+create. Return the initialized session."
   (require 'matlab)
   (org-babel-octave-initiate-session session params 'matlab))
 (defun org-babel-octave-initiate-session (&optional session params matlabp)
-  "Create an octave inferior process buffer.  If there is not a
-current inferior-process-buffer in SESSION then create. Return
-the initialized session."
+  "Create an octave inferior process buffer.
+If there is not a current inferior-process-buffer in SESSION then
+create. Return the initialized session."
   (require 'octave-inf)
   (unless (string= session "none")
     (let ((session (or session
@@ -162,10 +162,10 @@ the initialized session."
 
 (defun org-babel-octave-evaluate
   (session body result-type lang &optional matlabp)
-  "Pass BODY to the octave process in SESSION.  If RESULT-TYPE
-equals 'output then return 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 octave process in SESSION.
+If RESULT-TYPE equals 'output then return 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 session
       (org-babel-octave-evaluate-session session body result-type matlabp)
     (org-babel-octave-evaluate-external-process body result-type matlabp)))
@@ -241,8 +241,9 @@ statement in BODY, as elisp."
 	 (mapconcat #'identity (reverse results) "\n"))))))
 
 (defun org-babel-octave-import-elisp-from-file (file-name)
-  "Import data from FILE-NAME.  This removes initial blank and
-comment lines and then calls `org-babel-import-elisp-from-file'."
+  "Import data from FILE-NAME.
+This removes initial blank and comment lines and then calls
+`org-babel-import-elisp-from-file'."
   (let ((temp-file (make-temp-file "org-babel-results-")) beg end)
     (with-temp-file temp-file
       (insert-file-contents file-name)

lisp/ob-perl.el

@@ -50,8 +50,8 @@
       vars "\n") "\n" (org-babel-trim body) "\n")))
 
 (defun org-babel-execute:perl (body params)
-  "Execute a block of Perl code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
+  "Execute a block of Perl code with Babel.
+This function is called by `org-babel-execute-src-block'."
   (let* ((processed-params (org-babel-process-params params))
          (session (nth 0 processed-params))
          (vars (nth 1 processed-params))
@@ -68,13 +68,14 @@ called by `org-babel-execute-src-block'."
       (nth 5 processed-params) (cdr (assoc :rownames params))))))
 
 (defun org-babel-prep-session:perl (session params)
-  "Prepare SESSION according to the header arguments specified in PARAMS."
+  "Prepare SESSION according to the header arguments in PARAMS."
   (error "Sessions are not supported for Perl."))
 
 ;; helper functions
 
 (defun org-babel-perl-var-to-perl (var)
-  "Convert an elisp var into a string of perl source code
+  "Convert an elisp value to a perl variable.
+The elisp value, VAR, is converted to a string of perl source code
 specifying a var of the same value."
   (if (listp var)
       (concat "[" (mapconcat #'org-babel-perl-var-to-perl var ", ") "]")
@@ -83,7 +84,7 @@ specifying a var of the same value."
 (defvar org-babel-perl-buffers '(:default . nil))
 
 (defun org-babel-perl-initiate-session (&optional session params)
-  "Simply return nil, as sessions are not supported by perl"
+  "Return nil because sessions are not supported by perl"
 nil)
 
 (defvar org-babel-perl-wrapper-method
@@ -99,10 +100,10 @@ print o join(\"\\n\", @r), \"\\n\"")
   nil)
 
 (defun org-babel-perl-evaluate (session body &optional result-type)
-  "Pass BODY to the Perl 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 Perl 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."
   (when session (error "Sessions are not supported for Perl."))
   (case result-type
     (output (org-babel-eval org-babel-perl-command body))

lisp/ob-python.el

@@ -42,7 +42,7 @@
 (defvar org-babel-default-header-args:python '())
 
 (defvar org-babel-python-command "python"
-  "Name of command to use for executing python code.")
+  "Name of command for executing python code.")
 
 (defvar org-babel-python-mode (if (featurep 'xemacs) 'python-mode 'python)
   "Preferred python mode for use in running python interactively.")
@@ -59,8 +59,8 @@
    "\n" (org-babel-trim body) "\n"))
 
 (defun org-babel-execute:python (body params)
-  "Execute a block of Python code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
+  "Execute a block of Python code with Babel.
+This function is called by `org-babel-execute-src-block'."
   (let* ((processed-params (org-babel-process-params params))
          (session (org-babel-python-initiate-session (first processed-params)))
          (result-params (nth 2 processed-params))
@@ -78,7 +78,7 @@ called by `org-babel-execute-src-block'."
 			      (cdr (assoc :rownames params)))))))
 
 (defun org-babel-prep-session:python (session params)
-  "Prepare SESSION according to the header arguments specified in PARAMS."
+  "Prepare SESSION according to the header arguments in PARAMS."
   (let* ((session (org-babel-python-initiate-session session))
          (vars (org-babel-ref-variables params))
          (var-lines (mapcar ;; define any variables
@@ -105,14 +105,16 @@ called by `org-babel-execute-src-block'."
 ;; helper functions
 
 (defun org-babel-python-var-to-python (var)
-  "Convert an elisp var into a string of python source code
-specifying a var of the same value."
+  "Convert an elisp value to a python variable.
+Convert an elisp value, VAR, into a string of python source code
+specifying a variable of the same value."
   (if (listp var)
       (concat "[" (mapconcat #'org-babel-python-var-to-python var ", ") "]")
     (if (equal var 'hline) "None" (format "%S" var))))
 
 (defun org-babel-python-table-or-string (results)
-  "If the results look like a list or tuple, then convert them into an
+  "Convert RESULTS into an appropriate elisp value.
+If the results look like a list or tuple, then convert them into an
 Emacs-lisp table, otherwise return the results as a string."
   ((lambda (res)
      (if (listp res)
@@ -137,7 +139,8 @@ Emacs-lisp table, otherwise return the results as a string."
   (cdr (assoc session org-babel-python-buffers)))
 
 (defun org-babel-python-initiate-session-by-key (&optional session)
-  "If there is not a current inferior-process-buffer in SESSION
+  "Initiate a python session.
+If there is not a current inferior-process-buffer in SESSION
 then create.  Return the initialized session."
   (require org-babel-python-mode)
   (save-window-excursion
@@ -172,7 +175,7 @@ then create.  Return the initialized session."
      (org-babel-python-initiate-session-by-key session))))
 
 (defvar org-babel-python-eoe-indicator "'org_babel_python_eoe'"
-  "Used to indicate that evaluation is has completed.")
+  "A string to indicate that evaluation has completed.")
 (defvar org-babel-python-wrapper-method
   "
 def main():
@@ -189,10 +192,10 @@ open('%s', 'w').write( pprint.pformat(main()) )")
 
 (defun org-babel-python-evaluate
   (buffer body &optional result-type result-params)
-  "Pass BODY to the Python 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 Python 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 (not buffer)
       ;; external process evaluation
       (case result-type

lisp/ob-ref.el

@@ -57,8 +57,9 @@
 (declare-function org-at-table-p "org" (&optional table-type))
 
 (defun org-babel-ref-variables (params)
-  "Takes a parameter alist, and return an alist of variable
-names, and the emacs-lisp representation of the related value."
+  "Convert PARAMS to variable names and values.
+Takes a parameter alist, and return an alist of variable names,
+and the emacs-lisp representation of the related value."
   (let ((assignments
 	 (delq nil (mapcar (lambda (pair) (if (eq (car pair) :var) (cdr pair))) params)))
 	(others
@@ -69,13 +70,14 @@ names, and the emacs-lisp representation of the related value."
   "[ \f\t\n\r\v]*\\(.+?\\)[ \f\t\n\r\v]*=[ \f\t\n\r\v]*\\(.+\\)[ \f\t\n\r\v]*")
 
 (defun org-babel-ref-parse (assignment &optional params)
-  "Parse a variable ASSIGNMENT in a header argument.  If the
-right hand side of the assignment has a literal value return that
-value, otherwise interpret as a reference to an external resource
-and find it's value using `org-babel-ref-resolve-reference'.
-Return a list with two elements.  The first element of the list
-will be the name of the variable, and the second will be an
-emacs-lisp representation of the value of the variable."
+  "Parse a variable ASSIGNMENT in a header argument.
+If the right hand side of the assignment has a literal value
+return that value, otherwise interpret as a reference to an
+external resource and find it's value using
+`org-babel-ref-resolve-reference'.  Return a list with two
+elements.  The first element of the list will be the name of the
+variable, and the second will be an emacs-lisp representation of
+the value of the variable."
   (if (string-match org-babel-ref-split-regexp assignment)
       (let ((var (match-string 1 assignment))
             (ref (match-string 2 assignment)))
@@ -86,7 +88,8 @@ emacs-lisp representation of the value of the variable."
 		   val)) (org-babel-ref-literal ref))))))
 
 (defun org-babel-ref-literal (ref)
-  "Determine if the right side of a header argument variable
+  "Return the value of REF if it is a literal value.
+Determine if the right side of a header argument variable
 assignment is a literal value or is a reference to some external
 resource.  REF should be a string of the right hand side of the
 assignment.  If REF is literal then return it's value, otherwise
@@ -173,11 +176,11 @@ return nil."
 	    result))))))
 
 (defun org-babel-ref-index-list (index lis)
-  "Return the subset of LIS indexed by INDEX.  If INDEX is
-separated by ,s then each PORTION is assumed to index into the
-next deepest nesting or dimension.  A valid PORTION can consist
-of either an integer index, or two integers separated by a : in
-which case the entire range is returned."
+  "Return the subset of LIS indexed by INDEX.
+If INDEX is separated by ,s then each PORTION is assumed to index
+into the next deepest nesting or dimension.  A valid PORTION can
+consist of either an integer index, or two integers separated by
+a : in which case the entire range is returned."
   (if (string-match "^,?\\([^,]+\\)" index)
       (let ((length (length lis))
             (portion (match-string 1 index))
@@ -218,9 +221,9 @@ which case the entire range is returned."
 
 (defvar org-bracket-link-regexp)
 (defun org-babel-ref-at-ref-p ()
-  "Return the type of reference located at point or nil if none
-of the supported reference types are found.  Supported reference
-types are tables and source blocks."
+  "Return the type of reference located at point.
+Return nil if none of the supported reference types are found.
+Supported reference types are tables and source blocks."
   (cond ((org-at-table-p) 'table)
         ((looking-at "^[ \t]*#\\+BEGIN_SRC") 'source-block)
         ((looking-at org-bracket-link-regexp) 'file)

lisp/ob-ruby.el

@@ -65,8 +65,8 @@
       vars "\n") "\n" body "\n")))
 
 (defun org-babel-execute:ruby (body params)
-  "Execute a block of Ruby code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
+  "Execute a block of Ruby code with Babel.
+This function is called by `org-babel-execute-src-block'."
   (let* ((processed-params (org-babel-process-params params))
          (session (org-babel-ruby-initiate-session (first processed-params)))
          (result-params (nth 2 processed-params))
@@ -114,14 +114,16 @@ called by `org-babel-execute-src-block'."
 ;; helper functions
 
 (defun org-babel-ruby-var-to-ruby (var)
-  "Convert an elisp var into a string of ruby source code
-specifying a var of the same value."
+  "Convert VAR into a ruby variable.
+Convert an elisp value into a string of ruby source code
+specifying a variable of the same value."
   (if (listp var)
       (concat "[" (mapconcat #'org-babel-ruby-var-to-ruby var ", ") "]")
     (format "%S" var)))
 
 (defun org-babel-ruby-table-or-string (results)
-  "If RESULTS look like a table, then convert them into an
+  "Convert RESULTS into an appropriate elisp value.
+If RESULTS look like a table, then convert them into an
 Emacs-lisp table, otherwise return the results as a string."
   (org-babel-read
    (if (and (stringp results) (string-match "^\\[.+\\]$" results))
@@ -135,7 +137,8 @@ Emacs-lisp table, otherwise return the results as a string."
      results)))
 
 (defun org-babel-ruby-initiate-session (&optional session params)
-  "If there is not a current inferior-process-buffer in SESSION
+  "Initiate a ruby session.
+If there is not a current inferior-process-buffer in SESSION
 then create one.  Return the initialized session."
   (require 'inf-ruby)
   (unless (string= session "none")
@@ -147,7 +150,7 @@ then create one.  Return the initialized session."
         (org-babel-ruby-initiate-session session)))))
 
 (defvar org-babel-ruby-eoe-indicator ":org_babel_ruby_eoe"
-  "Used to indicate that evaluation is has completed.")
+  "String to indicate that evaluation has completed.")
 (defvar org-babel-ruby-f-write
   "File.open('%s','w'){|f| f.write((_.class == String) ? _ : _.inspect)}")
 (defvar org-babel-ruby-pp-f-write
@@ -175,10 +178,10 @@ end
 
 (defun org-babel-ruby-evaluate
   (buffer body &optional result-type result-params)
-  "Pass BODY to the Ruby 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 Ruby 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 (not buffer)
       ;; external process evaluation
       (case result-type

lisp/ob-sass.el

@@ -47,8 +47,8 @@
   "Expand BODY according to PARAMS, return the expanded body." body)
 
 (defun org-babel-execute:sass (body params)
-  "Execute a block of Sass code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
+  "Execute a block of Sass code with Babel.
+This function is called by `org-babel-execute-src-block'."
   (let* ((result-params (split-string (or (cdr (assoc :results params)) "")))
          (file (cdr (assoc :file params)))
          (out-file (or file (make-temp-file "org-babel-sass-out")))
@@ -60,7 +60,7 @@ called by `org-babel-execute-src-block'."
     (or file (with-temp-buffer (insert-file-contents out-file) (buffer-string)))))
 
 (defun org-babel-prep-session:sass (session params)
-  "This function does nothing as sass does not support sessions."
+  "Raise an error because sass does not support sessions."
   (error "Sass does not support sessions"))
 
 (provide 'ob-sass)

lisp/ob-screen.el

@@ -49,7 +49,7 @@ In case you want to use a different screen than one selected by your $PATH")
   "Expand BODY according to PARAMS, return the expanded body." body)
 
 (defun org-babel-execute:screen (body params)
-  "Send a block of code via screen to a terminal using org-babel.
+  "Send a block of code via screen to a terminal using Babel.
 \"default\" session is be used when none is specified."
   (message "Sending source code block to interactive terminal session...")
   (save-window-excursion
@@ -82,7 +82,7 @@ In case you want to use a different screen than one selected by your $PATH")
 ;; helper functions
 
 (defun org-babel-screen-session-execute-string (session body)
-  "If SESSION exist, send BODY to it."
+  "If SESSION exists, send BODY to it."
   (let ((socket (org-babel-screen-session-socketname session)))
     (when socket
       (let ((tmpfile (org-babel-screen-session-write-temp-file session body)))
@@ -93,7 +93,7 @@ In case you want to use a different screen than one selected by your $PATH")
                       "paste z"))))))
 
 (defun org-babel-screen-session-socketname (session)
-  "Check if SESSION exist by parsing output of \"screen -ls\"."
+  "Check if SESSION exists by parsing output of \"screen -ls\"."
   (let* ((screen-ls (shell-command-to-string "screen -ls"))
          (sockets (delq
 		   nil
@@ -125,8 +125,8 @@ In case you want to use a different screen than one selected by your $PATH")
     tmpfile))
 
 (defun org-babel-screen-test ()
-  "Test if the default setup works.  The terminal should shortly
-flicker."
+  "Test if the default setup works.
+The terminal should shortly flicker."
   (interactive)
   (let* ((session "org-babel-testing")
          (random-string (format "%s" (random 99999)))

lisp/ob-sh.el

@@ -43,8 +43,8 @@
 (defvar org-babel-default-header-args:sh '())
 
 (defvar org-babel-sh-command "sh"
-  "Command used to invoke a shell.  This will be passed to
-  `shell-command-on-region'")
+  "Command used to invoke a shell.
+This will be passed to  `shell-command-on-region'")
 
 (defun org-babel-expand-body:sh (body params &optional processed-params)
   "Expand BODY according to PARAMS, return the expanded body."
@@ -59,8 +59,8 @@
     vars "\n") "\n" body "\n\n")))
 
 (defun org-babel-execute:sh (body params)
-  "Execute a block of Shell commands with org-babel.  This
-function is called by `org-babel-execute-src-block'."
+  "Execute a block of Shell commands with Babel.
+This function is called by `org-babel-execute-src-block'."
   (let* ((processed-params (org-babel-process-params params))
          (session (org-babel-sh-initiate-session (nth 0 processed-params)))
          (result-params (nth 2 processed-params)) 
@@ -102,8 +102,9 @@ function is called by `org-babel-execute-src-block'."
 ;; helper functions
 
 (defun org-babel-sh-var-to-sh (var &optional sep)
-  "Convert an elisp var into a string of shell commands
-specifying a var of the same value."
+  "Convert an elisp value to a shell variable.
+Convert an elisp var into a string of shell commands specifying a
+var of the same value."
   (if (listp var)
       (flet ((deep-string (el)
                           (if (listp el)
@@ -115,7 +116,8 @@ specifying a var of the same value."
     (if (stringp var) (format "%s" var) (format "%S" var))))
 
 (defun org-babel-sh-table-or-results (results)
-  "If the results look like a table, then convert them into an
+  "Convert RESULTS to an appropriate elisp value.
+If the results look like a table, then convert them into an
 Emacs-lisp table, otherwise return the results as a string."
   (org-babel-read
    (if (string-match "^\\[.+\\]$" results)
@@ -136,15 +138,15 @@ Emacs-lisp table, otherwise return the results as a string."
           (progn (shell session) (get-buffer (current-buffer)))))))
 
 (defvar org-babel-sh-eoe-indicator "echo 'org_babel_sh_eoe'"
-  "Used to indicate that evaluation is has completed.")
+  "String to indicate that evaluation has completed.")
 (defvar org-babel-sh-eoe-output "org_babel_sh_eoe"
-  "Used to indicate that evaluation is has completed.")
+  "String to indicate that evaluation has completed.")
 
 (defun org-babel-sh-evaluate (session body &optional result-params)
-  "Pass BODY to the Shell 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."
+  "Pass BODY to the Shell 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."
   ((lambda (results)
      (if (or (member "scalar" result-params)
 	     (member "output" result-params))

lisp/ob-sql.el

@@ -54,8 +54,8 @@
   "Expand BODY according to PARAMS, return the expanded body." body)
 
 (defun org-babel-execute:sql (body params)
-  "Execute a block of Sql code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
+  "Execute a block of Sql code with Babel.
+This function is called by `org-babel-execute-src-block'."
   (let* ((result-params (split-string (or (cdr (assoc :results params)) "")))
 	 (processed-params (org-babel-process-params params))
          (cmdline (cdr (assoc :cmdline params)))
@@ -80,7 +80,7 @@ called by `org-babel-execute-src-block'."
 
 
 (defun org-babel-prep-session:sql (session params)
-  "Prepare SESSION according to the header arguments specified in PARAMS."
+  "Raise an error because Sql sessions aren't implemented."
   (error "sql sessions not yet implemented"))
 
 (provide 'ob-sql)

lisp/ob-sqlite.el

@@ -48,8 +48,8 @@
 (defvar org-babel-sqlite3-command "sqlite3")
 
 (defun org-babel-execute:sqlite (body params)
-  "Execute a block of Sqlite code with org-babel.  This function is
-called by `org-babel-execute-src-block'."
+  "Execute a block of Sqlite code with Babel.
+This function is called by `org-babel-execute-src-block'."
   (let ((result-params (split-string (or (cdr (assoc :results params)) "")))
 	(vars (org-babel-ref-variables params))
 	(db (cdr (assoc :db params)))
@@ -141,7 +141,8 @@ called by `org-babel-execute-src-block'."
     table))
 
 (defun org-babel-prep-session:sqlite (session params)
-  "Prepare SESSION according to the header arguments specified in PARAMS."
+  "Raise an error because support for sqlite sessions isn't implemented.
+Prepare SESSION according to the header arguments specified in PARAMS."
   (error "sqlite sessions not yet implemented"))
 
 (provide 'ob-sqlite)

lisp/ob-table.el

@@ -54,15 +54,16 @@
 (require 'ob)
 
 (defun org-babel-table-truncate-at-newline (string)
-  "If STRING ends in a newline character, then remove the newline
+  "Replace newline character with ellipses.
+If STRING ends in a newline character, then remove the newline
 character and replace it with ellipses."
   (if (and (stringp string) (string-match "[\n\r]" string))
       (concat (substring string 0 (match-beginning 0)) "...")
     string))
 
 (defmacro sbe (source-block &rest variables)
-  "Return the results of calling SOURCE-BLOCK assigning every
-variable in VARIABLES.  Each element of VARIABLES should be a two
+  "Return the results of calling SOURCE-BLOCK with VARIABLES.
+Each element of VARIABLES should be a two
 element list, whose first element is the name of the variable and
 second element is a string of its value.  The following call to
 `sbe' would be equivalent to the following source code block.

lisp/ob-tangle.el

@@ -56,10 +56,10 @@ then the name of the language is used."
 
 ;;;###autoload
 (defun org-babel-load-file (file)
-  "Load the contents of the Emacs Lisp source code blocks in the
-org-mode formatted FILE.  This function will first export the
-source code using `org-babel-tangle' and then load the resulting
-file using `load-file'."
+  "Load Emacs Lisp source code blocks in the Org-mode FILE.
+This function exports the source code using
+`org-babel-tangle' and then loads the resulting file using
+`load-file'."
   (flet ((age (file)
               (float-time
                (time-subtract (current-time)
@@ -76,11 +76,11 @@ file using `load-file'."
 
 ;;;###autoload
 (defun org-babel-tangle-file (file &optional target-file lang)
-  "Extract the bodies of all source code blocks in FILE with
-`org-babel-tangle'.  Optional argument TARGET-FILE can be used to
-specify a default export file for all source blocks.  Optional
-argument LANG can be used to limit the exported source code
-blocks by language."
+  "Extract the bodies of source code blocks in FILE.
+Source code blocks are extracted with `org-babel-tangle'.
+Optional argument TARGET-FILE can be used to specify a default
+export file for all source blocks.  Optional argument LANG can be
+used to limit the exported source code blocks by language."
   (interactive "fFile to tangle: \nP")
   (let ((visited-p (get-file-buffer (expand-file-name file)))
 	to-be-removed)
@@ -97,7 +97,8 @@ blocks by language."
 
 ;;;###autoload
 (defun org-babel-tangle (&optional target-file lang)
-  "Extract the bodies of all source code blocks from the current
+  "Write code blocks to source-specific files.
+Extract the bodies of all source code blocks from the current
 file into their own source-specific files.  Optional argument
 TARGET-FILE can be used to specify a default export file for all
 source blocks.  Optional argument LANG can be used to limit the
@@ -181,7 +182,8 @@ exported source code blocks by language."
       path-collector)))
 
 (defun org-babel-tangle-clean ()
-  "Call this function inside of a source-code file generated by
+  "Remove comments inserted by `org-babel-tangle'.
+Call this function inside of a source-code file generated by
 `org-babel-tangle' to remove all comments inserted automatically
 by `org-babel-tangle'.  Warning, this comment removes any lines
 containing constructs which resemble org-mode file links or noweb
@@ -195,7 +197,7 @@ references."
 
 (defvar org-stored-links)
 (defun org-babel-tangle-collect-blocks (&optional lang)
-  "Collect all source blocks in the current org-mode file.
+  "Collect source blocks in the current Org-mode file.
 Return an association list of source-code block specifications of
 the form used by `org-babel-spec-to-string' grouped by language.
 Optional argument LANG can be used to limit the collected source
@@ -255,7 +257,8 @@ code blocks by language."
     blocks))
 
 (defun org-babel-spec-to-string (spec)
-  "Insert the source-code specified by SPEC into the current
+  "Insert SPEC into the current file.
+Insert the source-code specified by SPEC into the current
 source code file.  This function uses `comment-region' which
 assumes that the appropriate major-mode is set.  SPEC has the
 form

lisp/ob.el

@@ -68,7 +68,8 @@
   :group 'org)
 
 (defcustom org-confirm-babel-evaluate t
-    "Require confirmation before interactively evaluating code
+  "Confirm before evaluation.
+Require confirmation before interactively evaluating code
 blocks in Org-mode buffers.  The default value of this variable
 is t, meaning confirmation is required for any code block
 evaluation.  This variable can be set to nil to inhibit any
@@ -90,8 +91,7 @@ remove code block execution from the C-c C-c keybinding."
 (put 'org-confirm-babel-evaluate 'safe-local-variable (lambda (x) (eq x t)))
 
 (defcustom org-babel-no-eval-on-ctrl-c-ctrl-c nil
-  "This variable can be set to remove code block evaluation from
-the C-c C-c key binding."
+  "Remove code block evaluation from the C-c C-c key binding."
   :group 'org-babel
   :type 'boolean)
 
@@ -127,7 +127,7 @@ the C-c C-c key binding."
   "Regexp used to identify inline src-blocks.")
 
 (defun org-babel-get-src-block-info (&optional header-vars-only)
-  "Get information of the current source block.
+  "Get information on the current source block.
 
 Returns a list
  (language body header-arguments-alist switches name function-args indent).
@@ -173,11 +173,11 @@ added to the header-arguments-alist."
         nil))))
 
 (defun org-babel-confirm-evaluate (info)
-  "Confirm that the user wishes to evaluate the code block
-defined by INFO.  This behavior can be suppressed by setting the
-value of `org-confirm-babel-evaluate' to nil, in which case all
-future interactive code block evaluations will proceed without
-any confirmation from the user.
+  "Confirm evaluation of the code block INFO.
+This behavior can be suppressed by setting the value of
+`org-confirm-babel-evaluate' to nil, in which case all future
+interactive code block evaluations will proceed without any
+confirmation from the user.
 
 Note disabling confirmation may result in accidental evaluation
 of potentially harmful code."
@@ -196,7 +196,8 @@ of potentially harmful code."
 
 ;;;###autoload
 (defun org-babel-execute-src-block-maybe ()
-  "Detect if this is context for a org-babel src-block and if so
+  "Conditionally execute a source block.
+Detect if this is context for a Babel src-block and if so
 then run `org-babel-execute-src-block'."
   (interactive)
   (if (not org-babel-no-eval-on-ctrl-c-ctrl-c)
@@ -208,7 +209,8 @@ then run `org-babel-execute-src-block'."
 
 ;;;###autoload
 (defun org-babel-expand-src-block-maybe ()
-  "Detect if this is context for a org-babel src-block and if so
+  "Conditionally expand a source block.
+Detect if this is context for a org-babel src-block and if so
 then run `org-babel-expand-src-block'."
   (interactive)
   (let ((info (org-babel-get-src-block-info)))
@@ -218,7 +220,8 @@ then run `org-babel-expand-src-block'."
 
 ;;;###autoload
 (defun org-babel-load-in-session-maybe ()
-  "Detect if this is context for a org-babel src-block and if so
+  "Conditionally load a source block in a session.
+Detect if this is context for a org-babel src-block and if so
 then run `org-babel-load-in-session'."
   (interactive)
   (let ((info (org-babel-get-src-block-info)))
@@ -230,7 +233,8 @@ then run `org-babel-load-in-session'."
 
 ;;;###autoload
 (defun org-babel-pop-to-session-maybe ()
-  "Detect if this is context for a org-babel src-block and if so
+  "Conditionally pop to a session.
+Detect if this is context for a org-babel src-block and if so
 then run `org-babel-pop-to-session'."
   (interactive)
   (let ((info (org-babel-get-src-block-info)))
@@ -241,9 +245,9 @@ then run `org-babel-pop-to-session'."
 (defconst org-babel-header-arg-names
   '(cache cmdline colnames dir exports file noweb results
 	  session tangle var noeval comments)
-  "Common header arguments used by org-babel.  Note that
-individual languages may define their own language specific
-header arguments as well.")
+  "Common header arguments used by org-babel.
+Note that individual languages may define their own language
+specific header arguments as well.")
 
 (defvar org-babel-default-header-args
   '((:session . "none") (:results . "replace") (:exports . "code")
@@ -259,23 +263,25 @@ header arguments as well.")
 
 (defvar org-babel-result-regexp
   "^[ \t]*#\\+res\\(ults\\|name\\)\\(\\[\\([[:alnum:]]+\\)\\]\\)?\\:[ \t]*"
-  "Regular expression used to match result lines.  If the
-results are associated with a hash key then the hash will be
-saved in the second match data.")
+  "Regular expression used to match result lines.
+If the results are associated with a hash key then the hash will
+be saved in the second match data.")
 
 (defvar org-babel-result-w-name-regexp
   (concat org-babel-result-regexp
 	  "\\([^ ()\f\t\n\r\v]+\\)\\(\(\\(.*\\)\)\\|\\)"))
 
 (defvar org-babel-min-lines-for-block-output 10
-  "If number of lines of output is equal to or exceeds this
+  "The minimum number of lines for block output.
+If number of lines of output is equal to or exceeds this
 value, the output is placed in a #+begin_example...#+end_example
 block. Otherwise the output is marked as literal by inserting
 colons at the starts of the lines. This variable only takes
 effect if the :results output option is in effect.")
 
 (defvar org-babel-noweb-error-langs nil
-  "List of language for which errors should be raised when the
+  "Languages for which Babel will raise literate programming errors.
+List of languages for which errors should be raised when the
 source code block satisfying a noweb reference in this language
 can not be resolved.")
 
@@ -293,10 +299,10 @@ can not be resolved.")
 (defvar call-process-region)
 ;;;###autoload
 (defun org-babel-execute-src-block (&optional arg info params)
-  "Execute the current source code block, and insert the results
-into the buffer.  Source code execution and the collection and
-formatting of results can be controlled through a variety of
-header arguments.
+  "Execute the current source code block.
+Insert the results of execution into the buffer.  Source code
+execution and the collection and formatting of results can be
+controlled through a variety of header arguments.
 
 Optionally supply a value for INFO in the form returned by
 `org-babel-get-src-block-info'.
@@ -367,15 +373,17 @@ block."
       (setq call-process-region 'org-babel-call-process-region-original))))
 
 (defun org-babel-expand-body:generic (body params &optional processed-params)
-  "Expand a block of code with org-babel according to it's header
+  "Expand BODY with PARAMS.
+Expand a block of code with org-babel according to it's header
 arguments.  This generic implementation of body expansion is
 called for languages which have not defined their own specific
 org-babel-expand-body:lang function." body)
 
 ;;;###autoload
 (defun org-babel-expand-src-block (&optional arg info params)
-  "Expand the current source code block according to it's header
-arguments, and pop open the results in a preview buffer."
+  "Expand the current source code block.
+Expand according to the source code block's header
+arguments and pop open the results in a preview buffer."
   (interactive)
   (let* ((info (or info (org-babel-get-src-block-info)))
          (lang (nth 0 info))
@@ -395,9 +403,10 @@ arguments, and pop open the results in a preview buffer."
 
 ;;;###autoload
 (defun org-babel-load-in-session (&optional arg info)
-  "Load the body of the current source-code block.  Evaluate the
-header arguments for the source block before entering the
-session.  After loading the body this pops open the session."
+  "Load the body of the current source-code block.
+Evaluate the header arguments for the source block before
+entering the session.  After loading the body this pops open the
+session."
   (interactive)
   (let* ((info (or info (org-babel-get-src-block-info)))
          (lang (nth 0 info))
@@ -476,7 +485,8 @@ results already exist."
 
 ;;;###autoload
 (defun org-babel-execute-buffer (&optional arg)
-  "Call `org-babel-execute-src-block' on every source block in
+  "Execute source code blocks in a buffer.
+Call `org-babel-execute-src-block' on every source block in
 the current buffer."
   (interactive "P")
   (save-excursion
@@ -491,7 +501,8 @@ the current buffer."
 
 ;;;###autoload
 (defun org-babel-execute-subtree (&optional arg)
-  "Call `org-babel-execute-src-block' on every source block in
+  "Execute source code blocks in a subtree.
+Call `org-babel-execute-src-block' on every source block in
 the current subtree."
   (interactive "P")
   (save-restriction
@@ -512,15 +523,14 @@ the current subtree."
     hash))
 
 (defun org-babel-result-hash (&optional info)
-  "Return the in-buffer hash associated with the results
-specified in INFO."
+  "Return the in-buffer hash associated with INFO."
   (org-babel-where-is-src-block-result nil info)
   (org-babel-clean-text-properties (match-string 3)))
 
 (defun org-babel-hide-hash ()
-  "Hide the hash in the current results line.  Only the initial
-`org-babel-hash-show' characters of the hash will remain
-visible."
+  "Hide the hash in the current results line.
+Only the initial `org-babel-hash-show' characters of the hash
+will remain visible."
   (add-to-invisibility-spec '(org-babel-hide-hash . t))
   (save-excursion
     (when (and (re-search-forward org-babel-result-regexp nil t)
@@ -536,10 +546,10 @@ visible."
         (overlay-put ov1 'babel-hash hash)))))
 
 (defun org-babel-hide-all-hashes ()
-  "Hide the hash in the current buffer.  Only the initial
-`org-babel-hash-show' characters of each hash will remain
-visible.  This function should be called as part of the
-`org-mode-hook'."
+  "Hide the hash in the current buffer.
+Only the initial `org-babel-hash-show' characters of each hash
+will remain visible.  This function should be called as part of
+the `org-mode-hook'."
   (save-excursion
     (while (re-search-forward org-babel-result-regexp nil t)
       (goto-char (match-beginning 0))
@@ -548,9 +558,9 @@ visible.  This function should be called as part of the
 (add-hook 'org-mode-hook 'org-babel-hide-all-hashes)
 
 (defun org-babel-hash-at-point (&optional point)
-  "Return the value of the hash at `point'.  The hash is also
-added as the last element of the kill ring.  This can be called
-with C-c C-c."
+  "Return the value of the hash at POINT.
+The hash is also added as the last element of the kill ring.
+This can be called with C-c C-c."
   (interactive)
   (let ((hash (car (delq nil (mapcar
 			      (lambda (ol) (overlay-get ol 'babel-hash))
@@ -559,7 +569,8 @@ with C-c C-c."
 (add-hook 'org-ctrl-c-ctrl-c-hook 'org-babel-hash-at-point)
 
 (defun org-babel-result-hide-spec ()
-  "Add `org-babel-hide-result' as an invisibility spec for hiding
+  "Hide portions of results lines.
+Add `org-babel-hide-result' as an invisibility spec for hiding
 portions of results lines."
   (add-to-invisibility-spec '(org-babel-hide-result . t)))
 (add-hook 'org-mode-hook 'org-babel-result-hide-spec)
@@ -655,7 +666,8 @@ portions of results lines."
 
 (defvar org-file-properties)
 (defun org-babel-params-from-properties (&optional lang)
-  "Return an association list of any source block params which
+  "Retrieve parameters specified as properties.
+Return an association list of any source block params which
 may be specified in the properties of the current outline entry."
   (save-match-data
     (let (val sym)
@@ -677,7 +689,8 @@ may be specified in the properties of the current outline entry."
 		 (and (boundp sym) (eval sym))))))))))
 
 (defun org-babel-params-from-buffer ()
-  "Return an association list of any source block params which
+  "Retrieve per-buffer parameters.
+ Return an association list of any source block params which
 may be specified at the top of the current buffer."
   (or org-babel-current-buffer-properties
       (setq org-babel-current-buffer-properties
@@ -693,8 +706,7 @@ may be specified at the top of the current buffer."
 
 (defvar org-src-preserve-indentation)
 (defun org-babel-parse-src-block-match ()
-  "Parse the match data resulting from a match of the
-`org-babel-src-block-regexp'."
+  "Parse the results from a match of the `org-babel-src-block-regexp'."
   (let* ((block-indentation (length (match-string 1)))
 	 (lang (org-babel-clean-text-properties (match-string 2)))
          (lang-headers (intern (concat "org-babel-default-header-args:" lang)))
@@ -720,8 +732,7 @@ may be specified at the top of the current buffer."
 	  block-indentation)))
 
 (defun org-babel-parse-inline-src-block-match ()
-  "Parse the match data resulting from a match of the
-`org-babel-inline-src-block-regexp'."
+  "Parse the results from a match of the `org-babel-inline-src-block-regexp'."
   (let* ((lang (org-babel-clean-text-properties (match-string 2)))
          (lang-headers (intern (concat "org-babel-default-header-args:" lang))))
     (list lang
@@ -776,7 +787,8 @@ Return a list (session vars result-params result-type colnames rownames)."
   (remove 'hline table))
 
 (defun org-babel-get-colnames (table)
-  "Return a cons cell, the `car' of which contains the TABLE less
+  "Return the column names of TABLE.
+Return a cons cell, the `car' of which contains the TABLE less
 colnames, and the `cdr' of which contains a list of the column
 names."
   (if (equal 'hline (nth 1 table))
@@ -784,7 +796,8 @@ names."
     (cons (cdr table) (car table))))
 
 (defun org-babel-get-rownames (table)
-  "Return a cons cell, the `car' of which contains the TABLE less
+  "Return the row names of TABLE.
+Return a cons cell, the `car' of which contains the TABLE less
 colnames, and the `cdr' of which contains a list of the column
 names.  Note: this function removes any hlines in TABLE."
   (flet ((trans (table) (apply #'mapcar* #'list table)))
@@ -823,7 +836,8 @@ names.  Note: this function removes any hlines in TABLE."
         (cdr (car (last names)))))))
 
 (defun org-babel-disassemble-tables (vars hlines colnames rownames)
-  "Process the variables in VARS according to the HLINES,
+  "Parse tables for further processing.
+Process the variables in VARS according to the HLINES,
 ROWNAMES and COLNAMES header arguments.  Return a list consisting
 of the vars, cnames and rnames."
   (let (cnames rnames)
@@ -850,7 +864,8 @@ of the vars, cnames and rnames."
      cnames rnames)))
 
 (defun org-babel-reassemble-table (table colnames rownames)
-  "Given a TABLE and set of COLNAMES and ROWNAMES add the names
+  "Add column and row names to a table.
+Given a TABLE and set of COLNAMES and ROWNAMES add the names
 to the table for reinsertion to org-mode."
   (if (listp table)
       ((lambda (table)
@@ -862,7 +877,8 @@ to the table for reinsertion to org-mode."
     table))
 
 (defun org-babel-where-is-src-block-head ()
-  "Return the point at the beginning of the current source
+  "Find where the current source block begins.
+Return the point at the beginning of the current source
 block.  Specifically at the beginning of the #+BEGIN_SRC line.
 If the point is not on a source block then return nil."
   (let ((initial (point)) top bottom)
@@ -935,7 +951,8 @@ org-babel-named-src-block-regexp."
       (message "result '%s' not found in this buffer" name))))
 
 (defun org-babel-find-named-result (name)
-  "Return the location of the result named NAME in the current
+  "Find a named result.
+Return the location of the result named NAME in the current
 buffer or nil if no such result exists."
   (save-excursion
     (goto-char (point-min))
@@ -973,7 +990,8 @@ With optional prefix argument ARG, jump backward ARG many source blocks."
 
 (defvar org-babel-lob-one-liner-regexp)
 (defun org-babel-where-is-src-block-result (&optional insert info hash indent)
-  "Return the point at the beginning of the result of the current
+  "Find where the current source block results begin.
+Return the point at the beginning of the result of the current
 source block.  Specifically at the beginning of the results line.
 If no result exists for this block then create a results line
 following the source block."
@@ -1076,8 +1094,9 @@ following the source block."
 
 (defvar org-link-types-re)
 (defun org-babel-read-link ()
-  "Read the link at `point' into emacs-lisp.  If the path of the
-link is a file path it is expanded using `expand-file-name'."
+  "Read the link at `point' into emacs-lisp.
+If the path of the link is a file path it is expanded using
+`expand-file-name'."
   (let* ((case-fold-search t)
          (raw (and (looking-at org-bracket-link-regexp)
                    (org-babel-clean-text-properties (match-string 1))))
@@ -1092,7 +1111,8 @@ link is a file path it is expanded using `expand-file-name'."
 
 (defun org-babel-insert-result
   (result &optional result-params info hash indent lang)
-  "Insert RESULT into the current buffer after the end of the
+  "Insert RESULT into the current buffer.
+By default RESULT is inserted after the end of the
 current source block.  With optional argument RESULT-PARAMS
 controls insertion of results in the org-mode file.
 RESULT-PARAMS can take the following values...
@@ -1232,9 +1252,9 @@ code ---- the results are extracted in the syntax of the source
       (point))))
 
 (defun org-babel-result-to-file (result)
-  "Convert RESULT into an `org-mode' link.  If the
-`default-directory' is different from the containing file's
-directory then expand relative links."
+  "Convert RESULT into an `org-mode' link.
+If the `default-directory' is different from the containing
+file's directory then expand relative links."
   (format
    "[[file:%s]]"
    (if (and default-directory
@@ -1266,9 +1286,9 @@ directory then expand relative links."
 	     (insert "#+end_example\n"))))))
 
 (defun org-babel-merge-params (&rest plists)
-  "Combine all parameter association lists in PLISTS.  Later
-elements of PLISTS override the values of previous element.  This
-takes into account some special considerations for certain
+  "Combine all parameter association lists in PLISTS.
+Later elements of PLISTS override the values of previous element.
+This takes into account some special considerations for certain
 parameters when merging lists."
   (let ((results-exclusive-groups
 	 '(("file" "vector" "table" "scalar" "raw" "org"
@@ -1367,10 +1387,10 @@ parameters when merging lists."
                                          params)))))))))
 
 (defun org-babel-expand-noweb-references (&optional info parent-buffer)
-  "This function expands Noweb style references in the body of
-the current source-code block.  For example the following
-reference would be replaced with the body of the source-code
-block named 'example-block'.
+  "Expand Noweb references in the body of the current source code block.
+
+For example the following reference would be replaced with the
+body of the source-code block named 'example-block'.
 
 <<example-block>>
 
@@ -1484,8 +1504,8 @@ This is taken almost directly from `org-read-prop'."
       (string-to-number string)))
 
 (defun org-babel-import-elisp-from-file (file-name)
-  "Read the results located at FILE-NAME into an elisp table.  If
-the table is trivial, then return it as a scalar."
+  "Read the results located at FILE-NAME into an elisp table.
+If the table is trivial, then return it as a scalar."
   (let (result)
     (save-window-excursion
       (with-temp-buffer
@@ -1517,8 +1537,8 @@ the table is trivial, then return it as a scalar."
   (apply 'string (reverse (string-to-list string))))
 
 (defun org-babel-chomp (string &optional regexp)
-  "Remove any trailing space or carriage returns characters from
-STRING.  Default regexp used is \"[ \f\t\n\r\v]\" but can be
+  "Strip trailing spaces and carriage returns from STRING.
+Default regexp used is \"[ \f\t\n\r\v]\" but can be
 overwritten by specifying a regexp as a second argument."
   (let ((regexp (or regexp "[ \f\t\n\r\v]")))
     (while (and (> (length string) 0)
@@ -1527,7 +1547,8 @@ overwritten by specifying a regexp as a second argument."
     string))
 
 (defun org-babel-trim (string &optional regexp)
-  "Like `org-babel-chomp' only it runs on both the front and back
+  "Strip leading and trailing spaces and carriage returns from STRING.
+Like `org-babel-chomp' only it runs on both the front and back
 of the string."
   (org-babel-chomp (org-babel-reverse-string
                     (org-babel-chomp (org-babel-reverse-string string) regexp))
@@ -1536,8 +1557,8 @@ of the string."
 (defvar org-babel-org-babel-call-process-region-original nil)
 (defun org-babel-tramp-handle-call-process-region
   (start end program &optional delete buffer display &rest args)
-  "Use tramp to handle call-process-region.  Fixes a bug in
-`tramp-handle-call-process-region'."
+  "Use tramp to handle call-process-region.
+Fixes a bug in `tramp-handle-call-process-region'."
   (if (and (featurep 'tramp) (file-remote-p default-directory))
       (let ((tmpfile (tramp-compat-make-temp-file "")))
 	(write-region start end tmpfile)
@@ -1553,7 +1574,8 @@ of the string."
            start end program delete buffer display args)))
 
 (defun org-babel-maybe-remote-file (file)
-  "If FILE specifies a remove file, then parse the information on
+  "Conditionally parse information on a remote connnection.
+If FILE specifies a remove file, then parse the information on
 the remote connection."
   (if (file-remote-p default-directory)
       (let* ((vec (tramp-dissect-file-name default-directory))