diff options
author | Tom Dye <tsd@tsdye.com> | 2010-07-13 16:04:47 -0700 |
---|---|---|
committer | Eric Schulte <schulte.eric@gmail.com> | 2010-07-13 16:04:47 -0700 |
commit | 3807787aa99797798db2663f49c8fae9dfa9718e (patch) | |
tree | 1c08075601e6c012977acf0342ff4c30418d093e | |
parent | c6403e0274d6e4fe9df0b5cc132c5379f50ec3d9 (diff) | |
download | org-mode-3807787aa99797798db2663f49c8fae9dfa9718e.tar.gz |
More docstring edits
-rw-r--r-- | lisp/ob-ditaa.el | 9 | ||||
-rw-r--r-- | lisp/ob-dot.el | 6 | ||||
-rw-r--r-- | lisp/ob-emacs-lisp.el | 4 | ||||
-rw-r--r-- | lisp/ob-eval.el | 10 | ||||
-rw-r--r-- | lisp/ob-exp.el | 50 |
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)) |