ensuring the existence of a complete first sentence in the documentation of each babel function

lisp/babel/langs/ob-C.el

@@ -51,6 +51,8 @@
   executable.")
 
 (defun org-babel-execute:cpp (body params)
+  "Execute BODY according to PARAMS.  This function calls
+`org-babel-execute:C'."
   (org-babel-execute:C body params))
 
 (defun org-babel-execute:c++ (body params)
@@ -74,8 +76,8 @@ header arguments (calls `org-babel-C-expand')."
   (let ((c-variant 'c)) (org-babel-C-expand body params processed-params)))
 
 (defun org-babel-C-execute (body params)
-  "This should only be called by `org-babel-execute:C' or
-`org-babel-execute:c++'."
+  "This function should only be called by `org-babel-execute:C'
+or `org-babel-execute:c++'."
   (message "executing C source code block")
   (let* ((processed-params (org-babel-process-params params))
          (tmp-src-file (make-temp-file "org-babel-C-src" nil
@@ -157,18 +159,21 @@ it's header arguments."
     (format "int main() {\n%s\n}\n" body)))
 
 (defun org-babel-prep-session:C (session params)
-  "C is a compiled languages -- no support for sessions"
+  "This function does nothing as C is a compiled language with no
+support for sessions"
   (error "C is a compiled languages -- no support for sessions"))
 
 (defun org-babel-load-session:C (session body params)
-  "C is a compiled languages -- no support for sessions"
+  "This function does nothing as C is a compiled language with no
+support for sessions"
   (error "C is a compiled languages -- no support for sessions"))
 
 ;; helper functions
 
 (defun org-babel-C-var-to-C (pair)
   "Convert an elisp val into a string of C code specifying a var
-of the same value.  TODO list support."
+of the same value."
+  ;; TODO list support
   (let ((var (car pair))
         (val (cdr pair)))
     (when (symbolp val)

lisp/babel/langs/ob-R.el

@@ -42,6 +42,7 @@
   "R-specific header arguments.")
 
 (defun org-babel-expand-body:R (body params &optional processed-params)
+  "Expand BODY according to PARAMS, return the expanded body."
   (let* ((processed-params (or processed-params
                                (org-babel-process-params params)))
 	 (vars (mapcar (lambda (i) (cons (car (nth i (second processed-params)))
@@ -144,7 +145,7 @@ called by `org-babel-execute-src-block'."
 			   (if (stringp session) session (buffer-name)))) (current-buffer))))))
 
 (defun org-babel-R-construct-graphics-device-call (out-file params)
-  "Construct the call to the graphics device"
+  "Construct the call to the graphics device."
   (let ((devices
 	 '((:bmp . "bmp")
 	   (:jpg . "jpeg")
@@ -242,9 +243,9 @@ last statement in BODY, as elisp."
 	      (delete nil (mapcar #'extractor (mapcar #'org-babel-chomp raw))) "\n"))))))))
 
 (defun org-babel-R-process-value-result (result column-names-p)
-  "R-specific processing of return value prior to return to org-babel.
-
-Currently, insert hline if column names in output have been requested."
+  "R-specific processing of return value prior to return to
+org-babel.  Insert hline if column names in output have been
+requested."
   (if column-names-p
       (cons (car result) (cons 'hline (cdr result)))
     result))

lisp/babel/langs/ob-asymptote.el

@@ -56,6 +56,7 @@
   "Default arguments to use when evaluating a asymptote source block.")
 
 (defun org-babel-expand-body:asymptote (body params &optional processed-params)
+  "Expand BODY according to PARAMS, return the expanded body."
   (let ((vars (second (or processed-params
                           (org-babel-process-params params)))))
     (concat (mapconcat 'org-babel-asymptote-var-to-asymptote vars "\n")
@@ -85,6 +86,7 @@ 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."
   (error "Asymptote does not support sessions"))
 
 (defun org-babel-asymptote-var-to-asymptote (pair)
@@ -133,10 +135,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/babel/langs/ob-clojure.el

@@ -70,10 +70,12 @@
 
 ;;taken mostly from clojure-test-mode.el
 (defun org-babel-clojure-clojure-slime-eval (string &optional handler)
+  "Evaluate a STRING of clojure code using `slime-eval-async'."
   (slime-eval-async `(swank:eval-and-grab-output ,string)
                     (or handler #'identity)))
 
 (defun org-babel-clojure-slime-eval-sync (string)
+  "Evaluate a STRING of clojure code using `slime-eval'."
   (slime-eval `(swank:eval-and-grab-output ,string)))
 
 ;;taken from swank-clojure.el
@@ -102,7 +104,7 @@
          "clojure.main"))))))
 
 (defun org-babel-clojure-table-or-string (results)
-  "If the results look like a table, then convert them into an
+  "If RESULTS looks 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)
@@ -123,7 +125,7 @@ specifying a var of the same value."
     (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 vars."
   (let ((vars-forms (mapconcat ;; define any variables
                       (lambda (pair)
                         (format "%s %s" (car pair) (org-babel-clojure-var-to-clojure (cdr pair))))
@@ -155,11 +157,12 @@ specifying a var of the same value."
 (defvar org-babel-clojure-pending-sessions '())
 
 (defun org-babel-clojure-session-buffer (session)
+  "Return the buffer associated with SESSION."
   (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
-then create.  Return the initialized session."
+then create one.  Return the initialized session."
   (save-window-excursion
     (let* ((session (if session
                         (if (stringp session) (intern session)
@@ -187,12 +190,12 @@ then create.  Return the initialized 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"
+or nil if \"none\" is specified."
   (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 setting up the bindings of org-babel session to a slime-clojure repl."
   (let ((pending-session (pop org-babel-clojure-pending-sessions)))
     (when pending-session
       (save-excursion
@@ -203,16 +206,19 @@ or nil if \"none\" is specified"
 (add-hook 'slime-connected-hook 'org-babel-clojure-session-connected-hook)
 
 (defun org-babel-clojure-bind-session-to-repl-buffer (session repl-buffer)
+  "Associate SESSION with REPL-BUFFER."
   (when (stringp session) (setq session (intern session)))
   (setq org-babel-clojure-buffers
         (cons (cons session repl-buffer)
               (assq-delete-all session org-babel-clojure-buffers))))
 
 (defun org-babel-clojure-repl-buffer-pred ()
-  "Predicate used to test whether the passed in buffer is an active slime-clojure repl buffer"
+  "Test whether the current buffer is an active slime-clojure
+repl buffer."
   (and (buffer-live-p (current-buffer)) (eq major-mode 'slime-repl-mode)))
 
 (defun org-babel-clojure-bind-session-to-repl (session)
+  "Bind SESSION to a clojure repl."
   (interactive "sEnter session name: ")
   (let ((repl-bufs (slime-filter-buffers 'org-babel-clojure-repl-buffer-pred)))
     (unless repl-bufs (error "No existing slime-clojure repl buffers exist"))
@@ -244,7 +250,7 @@ or nil if \"none\" is specified"
 	      (insert-file-contents (org-babel-maybe-remote-file tmp-file)) (buffer-string)))))))))
 
 (defun org-babel-clojure-evaluate-session (buffer body &optional result-type)
-  "Evaluate the body in the context of a clojure session"
+  "Evaluate the body in the context of a clojure session."
   (let ((raw nil)
         (results nil))
     (save-window-excursion
@@ -265,6 +271,7 @@ last statement in BODY, as elisp."
     (org-babel-clojure-evaluate-external-process buffer body result-type)))
 
 (defun org-babel-expand-body:clojure (body params &optional processed-params)
+  "Expand BODY according to PARAMS, return the expanded body."
   (org-babel-clojure-build-full-form
    body (second (or processed-params (org-babel-process-params params)))))
 

lisp/babel/langs/ob-css.el

@@ -36,7 +36,8 @@
 
 (add-to-list 'org-babel-tangle-langs '("css" "css" nil t))
 
-(defun org-babel-expand-body:css (body params &optional processed-params) body)
+(defun org-babel-expand-body:css (body params &optional processed-params)
+  "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

lisp/babel/langs/ob-ditaa.el

@@ -49,7 +49,8 @@
   '((:results . "file") (:exports . "results"))
   "Default arguments to use when evaluating a ditaa source block.")
 
-(defun org-babel-expand-body:ditaa (body params &optional processed-params) body)
+(defun org-babel-expand-body:ditaa (body params &optional processed-params)
+  "Expand BODY according to PARAMS, return the expanded body." body)
 
 (defun org-babel-execute:ditaa (body params)
   "Execute a block of Ditaa code with org-babel.  This function is
@@ -67,6 +68,8 @@ 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."
   (error "Ditaa does not support sessions"))
 
 (provide 'ob-ditaa)

lisp/babel/langs/ob-dot.el

@@ -50,7 +50,8 @@
 (defvar org-babel-default-header-args:dot '((:results . "file") (:exports . "results"))
   "Default arguments to use when evaluating a dot source block.")
 
-(defun org-babel-expand-body:dot (body params &optional processed-params) body)
+(defun org-babel-expand-body:dot (body params &optional processed-params)
+  "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
@@ -67,6 +68,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."
   (error "Dot does not support sessions"))
 
 (provide 'ob-dot)

lisp/babel/langs/ob-emacs-lisp.el

@@ -40,6 +40,7 @@
   "Default arguments to use when evaluating an emacs-lisp source block.")
 
 (defun org-babel-expand-body:emacs-lisp (body params &optional processed-params)
+  "Expand BODY according to PARAMS, return the expanded body."
   (let* ((processed-params (or processed-params (org-babel-process-params params)))
          (vars (second processed-params))
          (processed-params (org-babel-process-params params))

lisp/babel/langs/ob-gnuplot.el

@@ -56,8 +56,9 @@
 
 (defun org-babel-gnuplot-process-vars (params)
   "Extract variables from PARAMS and process the variables
-dumping all vectors into files returning an association list of
-variable names and the value to be used in the gnuplot code."
+dumping all vectors into files and returning an association list
+of variable names and the related value to be used in the gnuplot
+code."
   (mapcar
    (lambda (pair)
      (cons
@@ -69,6 +70,7 @@ variable names and the value to be used in the gnuplot code."
    (org-babel-ref-variables params)))
 
 (defun org-babel-expand-body:gnuplot (body params &optional processed-params)
+  "Expand BODY according to PARAMS, return the expanded body."
   (save-window-excursion
     (let* ((vars (org-babel-gnuplot-process-vars params))
            (out-file (cdr (assoc :file params)))
@@ -176,7 +178,7 @@ called by `org-babel-execute-src-block'."
 
 (defun org-babel-gnuplot-initiate-session (&optional session params)
   "If there is not a current inferior-process-buffer in SESSION
-then create.  Return the initialized session.  The current
+then create one.  Return the initialized session.  The current
 `gnuplot-mode' doesn't provide support for multiple sessions."
   (unless (string= session "none")
     (save-window-excursion (gnuplot-send-string-to-gnuplot "" "line")

lisp/babel/langs/ob-haskell.el

@@ -55,6 +55,7 @@
 (defvar org-babel-haskell-eoe "\"org-babel-haskell-eoe\"")
 
 (defun org-babel-expand-body:haskell (body params &optional processed-params)
+  "Expand BODY according to PARAMS, return the expanded body."
   (let (vars (second (or processed-params (org-babel-process-params params))))
     (concat
      (mapconcat
@@ -87,14 +88,14 @@
      (org-babel-pick-name (nth 5 processed-params) (cdr (assoc :rownames params))))))
 
 (defun org-babel-haskell-read-string (string)
-  "Strip \\\"s from around haskell string"
+  "Strip \\\"s from around a haskell string."
   (if (string-match "^\"\\([^\000]+\\)\"$" string)
       (match-string 1 string)
     string))
 
 (defun org-babel-haskell-initiate-session (&optional session params)
   "If there is not a current inferior-process-buffer in SESSION
-then create.  Return the initialized session."
+then create one.  Return the initialized session."
   ;; TODO: make it possible to have multiple sessions
   (run-haskell) (current-buffer))
 
@@ -141,7 +142,7 @@ Emacs-lisp table, otherwise return the results as a string."
      results)))
 
 (defun org-babel-haskell-export-to-lhs (&optional arg)
-  "Export to a .lhs with all haskell code blocks escaped
+  "Export to a .lhs file with all haskell code blocks escaped
 appropriately.  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

lisp/babel/langs/ob-latex.el

@@ -44,6 +44,7 @@
   "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."
   (mapc (lambda (pair) ;; replace variables
           (setq body
                 (replace-regexp-in-string
@@ -83,7 +84,8 @@ called by `org-babel-execute-src-block'."
     body))
 
 (defun org-babel-latex-body-to-tex-file (tex-file body &optional height width)
-  "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
@@ -101,7 +103,8 @@ called by `org-babel-execute-src-block'."
     (org-export-latex-fix-inputenc)))
 
 (defun org-babel-latex-tex-to-pdf (tex-file)
-  "Extracted from `org-export-as-pdf' in org-latex.el."
+  "Generate a pdf 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))
@@ -134,6 +137,7 @@ called by `org-babel-execute-src-block'."
       pdffile)))
 
 (defun org-babel-prep-session:latex (session params)
+  "Create a session named SESSION according to PARAMS."
   (error "Latex does not support sessions"))
 
 (provide 'ob-latex)

lisp/babel/langs/ob-matlab.el

@@ -48,7 +48,8 @@
 (defvar org-babel-matlab-shell-command "matlab -nosplash"
   "Shell command to use to run matlab as an external process.")
 
-(defun org-babel-expand-body:matlab (body params &optional processed-params) body)
+(defun org-babel-expand-body:matlab (body params &optional processed-params)
+  "Expand BODY according to PARAMS, return the expanded body." body)
 
 (defvar org-babel-matlab-with-emacs-link nil
   "If non-nil use matlab-shell-run-region for session
@@ -68,12 +69,13 @@ delete('%s')
   (org-babel-execute:octave body params 'matlab))
 
 (defun org-babel-prep-session:matlab (session params)
+  "Prepare SESSION according to PARAMS."
   (org-babel-prep-session:octave session params 'matlab))
 
 (defun org-babel-matlab-initiate-session (&optional session params)
-  "Create 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."
   (org-babel-octave-initiate-session session params 'matlab))
 
 (provide 'ob-matlab)

lisp/babel/langs/ob-ocaml.el

@@ -49,6 +49,7 @@
 (defvar org-babel-ocaml-eoe-output "org-babel-ocaml-eoe")
 
 (defun org-babel-expand-body:ocaml (body params &optional processed-params)
+  "Expand BODY according to PARAMS, return the expanded body."
   (let ((vars (second (or processed-params (org-babel-process-params params)))))
     (concat
      (mapconcat
@@ -83,6 +84,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."
   (let ((regexp "%s = \\(.+\\)$"))
     (cond
      ((string-match (format regexp "string") output)

lisp/babel/langs/ob-octave.el

@@ -42,6 +42,7 @@
   "Shell command to use to run octave as an external process.")
 
 (defun org-babel-expand-body:octave (body params &optional processed-params)
+  "Expand BODY according to PARAMS, return the expanded body."
   (let ((vars (second (or processed-params (org-babel-process-params params)))))
     (concat
      ;; prepend code to define all arguments passed to the code block
@@ -97,9 +98,9 @@ specifying a variable of the same value."
     session))
 
 (defun org-babel-octave-initiate-session (&optional session params matlabp)
-  "Create 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."
   (unless (string= session "none")
     (let ((session (or session (if matlabp "*Inferior Matlab*" "*Inferior Octave*"))))
       (if (org-babel-comint-buffer-livep session) session
@@ -120,15 +121,16 @@ end")
 (defvar org-babel-octave-eoe-output "ans = org_babel_eoe")
 
 (defun org-babel-octave-evaluate (session body result-type lang)
-  "Pass BODY to the octave process.
-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)))
 
 (defun org-babel-octave-evaluate-external-process (body result-type matlabp)
+  "Evaluate BODY in an external octave process."
   (let ((cmd (if matlabp org-babel-matlab-shell-command org-babel-octave-shell-command)))
     (save-excursion
       (case result-type
@@ -149,6 +151,7 @@ value of the last statement in BODY, as elisp."
 	   (org-babel-octave-import-elisp-from-file (org-babel-maybe-remote-file tmp-file))))))))
 
 (defun org-babel-octave-evaluate-session (session body result-type &optional matlabp)
+  "Evaluate BODY in SESSION."
   (let* ((tmp-file (make-temp-file "org-babel-results-"))
 	 (wait-file (make-temp-file "org-babel-matlab-emacs-link-wait-signal-"))
 	 (full-body
@@ -196,9 +199,8 @@ value of the last statement in BODY, as elisp."
 	 (mapconcat #'identity (reverse results) "\n"))))))
 
 (defun org-babel-octave-import-elisp-from-file (file-name)
-  "Import data written to file by octave.
-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/babel/langs/ob-perl.el

@@ -36,6 +36,7 @@
 (add-to-list 'org-babel-tangle-langs '("perl" "pl" "#!/usr/bin/env perl"))
 
 (defun org-babel-expand-body:perl (body params &optional processed-params)
+  "Expand BODY according to PARAMS, return the expanded body."
   (let ((vars (second (or processed-params (org-babel-process-params params)))))
     (concat
      (mapconcat ;; define any variables

lisp/babel/langs/ob-python.el

@@ -39,6 +39,7 @@
 (add-to-list 'org-babel-tangle-langs '("python" "py" "#!/usr/bin/env python"))
 
 (defun org-babel-expand-body:python (body params &optional processed-params)
+  "Expand BODY according to PARAMS, return the expanded body."
   (concat
    (mapconcat ;; define any variables
     (lambda (pair)
@@ -117,6 +118,7 @@ Emacs-lisp table, otherwise return the results as a string."
 (defvar org-babel-python-buffers '(:default . nil))
 
 (defun org-babel-python-session-buffer (session)
+  "Return the buffer associated with SESSION."
   (cdr (assoc session org-babel-python-buffers)))
 
 (defun org-babel-python-initiate-session-by-key (&optional session)
@@ -145,6 +147,7 @@ then create.  Return the initialized session."
       session)))
 
 (defun org-babel-python-initiate-session (&optional session params)
+  "Create a session named SESSION according to PARAMS."
   (unless (string= session "none")
     (org-babel-python-session-buffer (org-babel-python-initiate-session-by-key session))))
 

lisp/babel/langs/ob-ruby.el

@@ -47,6 +47,7 @@
 (add-to-list 'org-babel-tangle-langs '("ruby" "rb" "#!/usr/bin/env ruby"))
 
 (defun org-babel-expand-body:ruby (body params &optional processed-params)
+  "Expand BODY according to PARAMS, return the expanded body."
   (let ((vars (second (or processed-params (org-babel-process-params params)))))
     (concat
      (mapconcat ;; define any variables
@@ -113,7 +114,7 @@ specifying a var of the same value."
     (format "%S" var)))
 
 (defun org-babel-ruby-table-or-string (results)
-  "If the results look like a table, then convert them into an
+  "If RESULTS look like a table, then convert them into an
 Emacs-lisp table, otherwise return the results as a string."
   (message "converting %S" results)
   (org-babel-read
@@ -129,7 +130,7 @@ Emacs-lisp table, otherwise return the results as a string."
 
 (defun org-babel-ruby-initiate-session (&optional session params)
   "If there is not a current inferior-process-buffer in SESSION
-then create.  Return the initialized session."
+then create one.  Return the initialized session."
   (unless (string= session "none")
     (let ((session-buffer (save-window-excursion
 			    (run-ruby nil session) (current-buffer))))
@@ -227,7 +228,7 @@ last statement in BODY, as elisp."
            (org-babel-ruby-table-or-string (car results))))))))
 
 (defun org-babel-ruby-read-string (string)
-  "Strip \\\"s from around ruby string"
+  "Strip \\\"s from around a ruby string."
   (if (string-match "^\"\\([^\000]+\\)\"$" string)
       (match-string 1 string)
     string))

lisp/babel/langs/ob-sass.el

@@ -48,7 +48,8 @@
 
 (add-to-list 'org-babel-tangle-langs '("sass" "sass"))
 
-(defun org-babel-expand-body:sass (body params &optional processed-params) body)
+(defun org-babel-expand-body:sass (body params &optional processed-params)
+  "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
@@ -65,6 +66,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."
   (error "Sass does not support sessions"))
 
 (provide 'ob-sass)

lisp/babel/langs/ob-screen.el

@@ -50,7 +50,8 @@ In case you want to use a different screen than one selected by your $PATH")
   '((:results . "silent") (:session . "default") (:cmd . "sh") (:terminal . "xterm"))
   "Default arguments to use when running screen source blocks.")
 
-(defun org-babel-expand-body:screen (body params &optional processed-params) body)
+(defun org-babel-expand-body:screen (body params &optional processed-params)
+  "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.
@@ -121,8 +122,8 @@ In case you want to use a different screen than one selected by your $PATH")
     tmpfile))
 
 (defun org-babel-screen-test ()
-  "Command that tests 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/babel/langs/ob-sh.el

@@ -41,6 +41,7 @@
   `shell-command-on-region'")
 
 (defun org-babel-expand-body:sh (body params &optional processed-params)
+  "Expand BODY according to PARAMS, return the expanded body."
   (let ((vars (second (or processed-params (org-babel-process-params params))))
         (sep (cdr (assoc :separator params))))
     (concat
@@ -120,6 +121,7 @@ Emacs-lisp table, otherwise return the results as a string."
      results)))
 
 (defun org-babel-sh-initiate-session (&optional session params)
+  "Initiate a session named SESSION according to PARAMS."
   (unless (string= session "none")
     (save-window-excursion
       (or (org-babel-comint-buffer-livep session)
@@ -183,6 +185,7 @@ last statement in BODY."
             "")))))
 
 (defun org-babel-sh-strip-weird-long-prompt (string)
+  "Remove prompt cruft from a string of shell output."
   (while (string-match "^% +[\r\n$]+ *" string)
     (setq string (substring string (match-end 0))))
   string)

lisp/babel/langs/ob-sql.el

@@ -51,7 +51,8 @@
 
 (add-to-list 'org-babel-tangle-langs '("sql" "sql"))
 
-(defun org-babel-expand-body:sql (body params &optional processed-params) body)
+(defun org-babel-expand-body:sql (body params &optional processed-params)
+  "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

lisp/babel/ob-comint.el

@@ -37,6 +37,7 @@
 (require 'comint)
 
 (defun org-babel-comint-buffer-livep (buffer)
+  "Check if BUFFER is a comint buffer with a live process."
   (let ((buffer (if buffer (get-buffer buffer))))
     (and buffer (buffer-live-p buffer) (get-buffer-process buffer) buffer)))
 
@@ -111,9 +112,9 @@ during execution of body."
     (org-babel-comint-wait-for-output buffer)))
 
 (defun org-babel-comint-wait-for-output (buffer)
-  "Wait until output arrives.  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/babel/ob-lob.el

@@ -98,6 +98,7 @@ the word 'call'."
 		  (list (length (match-string 1))))))))
   
 (defun org-babel-lob-execute (info)
+  "Execute the lob call specified by INFO."
   (let ((params (org-babel-merge-params
 		 org-babel-default-header-args
 		 (org-babel-params-from-buffer)

lisp/babel/ob-ref.el

@@ -94,7 +94,7 @@ return nil."
       out)))
 
 (defun org-babel-ref-resolve-reference (ref &optional params)
-  "Resolve the reference and return its value"
+  "Resolve the reference REF and return its value."
   (save-excursion
     (let ((case-fold-search t)
           type args new-refere new-referent result lob-info split-file split-ref

lisp/babel/ob-table.el

@@ -56,6 +56,8 @@
 (require 'ob)
 
 (defun org-babel-table-truncate-at-newline (string)
+  "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))

lisp/babel/ob.el

@@ -152,11 +152,13 @@ can not be resolved.")
 (defvar org-babel-after-execute-hook nil
   "Hook for functions to be called after `org-babel-execute-src-block'")
 (defun org-babel-named-src-block-regexp-for-name (name)
-  "Regexp used to match named src block."
+  "This generates a regexp used to match a src block named NAME."
   (concat org-babel-source-name-regexp (regexp-quote name) "[ \t\n]*"
 	  (substring org-babel-src-block-regexp 1)))
 
 (defun org-babel-set-interpreters (var value)
+  "Update the regular expressions used to match block and inline
+code."
   (set-default var value)
   (setq
    org-babel-src-block-regexp
@@ -453,6 +455,7 @@ added to the header-arguments-alist."
         nil)))) ;; indicate that no source block was found
 
 (defun org-babel-sha1-hash (&optional info)
+  "Generate an sha1 hash based on the value of info."
   (interactive)
   (let* ((info (or info (org-babel-get-src-block-info)))
          (hash (sha1 (format "%s-%s" (mapconcat (lambda (arg) (format "%S" arg))
@@ -462,6 +465,8 @@ added to the header-arguments-alist."
     hash))
 
 (defun org-babel-result-hash (&optional info)
+  "Return the in-buffer hash associated with the results
+specified in INFO."
   (org-babel-where-is-src-block-result nil info)
   (org-babel-clean-text-properties (match-string 3)))
 
@@ -507,6 +512,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
+portions of results lines."
   (add-to-invisibility-spec '(org-babel-hide-result . t)))
 (add-hook 'org-mode-hook 'org-babel-result-hide-spec)
 
@@ -635,6 +642,8 @@ may be specified at the top of the current buffer."
 		   (org-match-string-no-properties 2))))))))
 
 (defun org-babel-parse-src-block-match ()
+  "Parse the match data resulting 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)))
@@ -660,6 +669,8 @@ 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'."
   (let* ((lang (org-babel-clean-text-properties (match-string 2)))
          (lang-headers (intern (concat "org-babel-default-header-args:" lang))))
     (list lang
@@ -714,17 +725,17 @@ 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 colnames, and the `cdr' of which contains a list of the
-        column names"
+  "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 (second table))
       (cons (cddr table) (car table))
     (cons (cdr table) (car table))))
 
 (defun org-babel-get-rownames (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"
+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)))
     (let* ((width (apply 'max (mapcar (lambda (el) (if (listp el) (length el) 0)) table)))
            (table (trans (mapcar (lambda (row)
@@ -1308,6 +1319,8 @@ block but are passed literally to the \"example-block\"."
     new-body))
 
 (defun org-babel-error-notify (exit-code stderr)
+  "Open a buffer containing information from STDERR with a
+message about the value of EXIT-CODE."
   (message (format "Shell command exited with code %d" exit-code))
   (let ((buf (get-buffer-create "*Org-Babel Error Output*")))
     (with-current-buffer buf
@@ -1341,7 +1354,7 @@ This is taken almost directly from `org-read-prop'."
     cell))
 
 (defun org-babel-number-p (string)
-  "Return t if STRING represents a number"
+  "Return t if STRING represents a number."
   (if (and (string-match "^-?[0-9]*\\.?[0-9]*$" string)
            (= (length (substring string (match-beginning 0)
 				 (match-end 0)))
@@ -1378,6 +1391,7 @@ the table is trivial, then return it as a scalar."
                       cell)))
 
 (defun org-babel-reverse-string (string)
+  "Return the reverse of STRING."
   (apply 'string (reverse (string-to-list string))))
 
 (defun org-babel-chomp (string &optional regexp)
@@ -1391,15 +1405,16 @@ 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 of the 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))
                    regexp))
 
 (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)
@@ -1415,6 +1430,8 @@ Fixes a bug in `tramp-handle-call-process-region'."
            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
+the remote connection."
   (if (file-remote-p default-directory)
       (let* ((vec (tramp-dissect-file-name default-directory))
              (user (tramp-file-name-user vec))