summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorTom Dye <tsd@tsdye.com>2010-07-13 16:04:47 -0700
committerEric Schulte <schulte.eric@gmail.com>2010-07-13 16:04:47 -0700
commit3807787aa99797798db2663f49c8fae9dfa9718e (patch)
tree1c08075601e6c012977acf0342ff4c30418d093e
parentc6403e0274d6e4fe9df0b5cc132c5379f50ec3d9 (diff)
downloadorg-mode-3807787aa99797798db2663f49c8fae9dfa9718e.tar.gz
More docstring edits
-rw-r--r--lisp/ob-ditaa.el9
-rw-r--r--lisp/ob-dot.el6
-rw-r--r--lisp/ob-emacs-lisp.el4
-rw-r--r--lisp/ob-eval.el10
-rw-r--r--lisp/ob-exp.el50
5 files changed, 41 insertions, 38 deletions
diff --git a/lisp/ob-ditaa.el b/lisp/ob-ditaa.el
index 3da2c75..cedb230 100644
--- a/lisp/ob-ditaa.el
+++ b/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)
diff --git a/lisp/ob-dot.el b/lisp/ob-dot.el
index 26db2d3..edf8f90 100644
--- a/lisp/ob-dot.el
+++ b/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)
diff --git a/lisp/ob-emacs-lisp.el b/lisp/ob-emacs-lisp.el
index d2b5602..148466d 100644
--- a/lisp/ob-emacs-lisp.el
+++ b/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
diff --git a/lisp/ob-eval.el b/lisp/ob-eval.el
index 40731a1..cfb19c7 100644
--- a/lisp/ob-eval.el
+++ b/lisp/ob-eval.el
@@ -32,8 +32,7 @@
(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))
@@ -42,8 +41,9 @@ message about the value of EXIT-CODE."
(message "Babel evaluation exited with code %d" 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
@@ -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'
diff --git a/lisp/ob-exp.el b/lisp/ob-exp.el
index a715abb..b500e55 100644
--- a/lisp/ob-exp.el
+++ b/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))