Fix some docstrings

10 files changed, 32 insertions, 34 deletions

diff --git a/lisp/init-bib.el b/lisp/init-bib.el
index 803b53e..420ca06 100644
--- a/lisp/init-bib.el
+++ b/lisp/init-bib.el
@@ -56,9 +56,9 @@ capitalized."
 
 (defun km/browse-doi (doi)
   "Open DOI in browser.
-The link is opened using the settings of `org-doi-server-url'.
-When called interactively, DOI is taken from the text under
-point."
+When called interactively, take the DOI from the text under
+point.  The link is opened using the settings of
+`org-doi-server-url'."
   (interactive (list (km/doi-at-point)))
   (browse-url (org-link-escape-browser (concat org-doi-server-url doi))))
 
diff --git a/lisp/init-buffile.el b/lisp/init-buffile.el
index 4d98780..33fa74d 100644
--- a/lisp/init-buffile.el
+++ b/lisp/init-buffile.el
@@ -36,9 +36,7 @@
 
 ;; http://emacs-fu.blogspot.com/2013/03/editing-with-root-privileges-once-more.html
 (defun km/find-file-as-root ()
-  "`ido-find-file` that automatically edits the file with
-root-privileges (using tramp/sudo) if the file is not writable by
-user."
+  "Automatically edit file with root-privileges."
   (interactive)
   (let ((file (ido-read-file-name "Edit as root: ")))
     (unless (file-writable-p file)
@@ -48,7 +46,7 @@ user."
 (global-set-key (kbd "C-x F") 'km/find-file-as-root)
 
 (defun km/save-and-kill-buffer ()
-  "Save current buffer and then kill it"
+  "Save current buffer and then kill it."
   (interactive)
   (save-buffer)
   (kill-this-buffer))
diff --git a/lisp/init-editing.el b/lisp/init-editing.el
index 2f4840d..a8f37ae 100644
--- a/lisp/init-editing.el
+++ b/lisp/init-editing.el
@@ -26,7 +26,7 @@
 
 ;; http://www.emacswiki.org/emacs/UnfillParagraph
 (defun km/unfill-paragraph ()
-  "Takes a multi-line paragraph and makes it into a single line of text."
+  "Convert a multi-line paragraph to a single line of text."
   (interactive)
   (let ((fill-column (point-max)))
     (fill-paragraph nil)))
@@ -80,16 +80,16 @@ special case.
 (defun km/narrow-to-comment-heading ()
   "Narrow to the current comment heading subtree.
 
+Narrow the buffer from the current comment heading to the next
+comment heading of the same level or, if not found, to the end of
+the buffer.
+
 A comment is considered a heading if it is at the beginning of
 the line and if it conists of 3 or more occurences of
 `comment-start'. The number of `comment-start' characters is
 taken to indicate the level of the heading (with 3 being the top
 level).
 
-The buffer will be narrowed from the current comment heading to
-the next comment heading of the same level or, if not found, to
-the end of the buffer.
-
 In the examples below, 'x' indicates the current point and '>>>'
 and '<<<' mark the bounds of the narrowed region.
 
@@ -133,7 +133,7 @@ and '<<<' mark the bounds of the narrowed region.
 (define-key narrow-map "c" 'km/narrow-to-comment-heading)
 
 (defun km/toggle-line-or-region-comment ()
-  "Comment/uncomment the current line or region"
+  "Comment/uncomment the current line or region."
     (interactive)
     (let (beg end)
       (if (region-active-p)
@@ -162,7 +162,7 @@ and '<<<' mark the bounds of the narrowed region.
   "If set, `km/cleanup-buffer' does not perform clean up on save.")
 
 (defun km/toggle-prevent-cleanup ()
-  "Toggle state of `km/prevent-cleanup'"
+  "Toggle state of `km/prevent-cleanup'."
   (interactive)
   (if km/prevent-cleanup
       (message "Allowing cleanup on save ")
@@ -188,7 +188,7 @@ and '<<<' mark the bounds of the narrowed region.
 
 ;; From http://whattheemacsd.com/key-bindings.el-01.html
 (defun km/goto-line-with-feedback ()
-  "Show line numbers temporarily, while prompting for the line number input"
+  "Show line numbers when prompting for the line number input."
   (interactive)
   (unwind-protect
       (progn
diff --git a/lisp/init-framewin.el b/lisp/init-framewin.el
index 238a56f..2425562 100644
--- a/lisp/init-framewin.el
+++ b/lisp/init-framewin.el
@@ -2,7 +2,7 @@
 
 ;; From prelude
 (defun km/swap-windows ()
-  "If you have 2 windows, it swaps them."
+  "Swap 2 windows."
   (interactive)
   (if (/= (count-windows) 2)
       (message "You need exactly 2 windows to do this.")
diff --git a/lisp/init-general.el b/lisp/init-general.el
index ee9c901..f5f28f7 100644
--- a/lisp/init-general.el
+++ b/lisp/init-general.el
@@ -49,7 +49,7 @@
 
 
 (defun km/imenu (rescan)
-  "Call `imenu', rescanning if RESCAN is non-nil"
+  "Call `imenu', rescanning if RESCAN is non-nil."
   (interactive "P")
   (when (and rescan
              ;; No need to rescan if imenu hasn't been autoloaded yet.
diff --git a/lisp/init-git.el b/lisp/init-git.el
index 3400375..85e0a9f 100644
--- a/lisp/init-git.el
+++ b/lisp/init-git.el
@@ -58,9 +58,9 @@ function for calling from outside Magit buffers."
 
 (defun km/magit-stage-file-intent (file)
   "Stage FILE but not its content.
-With a prefix argument or when there is no file at point ask for
-the file to be staged.  Otherwise stage the file at point without
-requiring confirmation.
+With a prefix argument or when there is no file at point, ask for
+the file to be staged.  Otherwise, stage the file at point
+without requiring confirmation.
 \n(git add -N FILE)"
   ;; Modified from `magit-stage-file'.
   (interactive
diff --git a/lisp/init-gnus.el b/lisp/init-gnus.el
index d9a39c8..7fbea37 100644
--- a/lisp/init-gnus.el
+++ b/lisp/init-gnus.el
@@ -180,9 +180,9 @@ A new buffer with the patch contents is opened in another window."
 (defun km/snip-mail-quote (beg end &optional number quote-char)
   "Replace region lines with \"[...]\".
 If prefix argument NUMBER is non-nil, add the number of lines
-that were snipped.  The default QUOTE-CHAR is \">\".  Text
-following the snipped lines is placed on a new line and the
-resulting paragraph is filled."
+that were snipped.  The default QUOTE-CHAR is \">\".  Place text
+following the snipped lines on a new line, and file the resulting
+paragraph."
   (interactive "r\nP")
   (let ((nlines (count-lines beg end))
         (quote-char (or quote-char ">")))
diff --git a/lisp/init-org.el b/lisp/init-org.el
index ef49d32..963dfd3 100644
--- a/lisp/init-org.el
+++ b/lisp/init-org.el
@@ -180,8 +180,8 @@ number, which has a different meaning, it is left untouched."
 
 (defun km/org-tree-to-indirect-buffer-current-window (&optional arg)
   "Create indirect buffer and narrow to subtree in this window.
-Before running `org-tree-to-indirect-buffer',
-`org-indirect-buffer-display' is set to `current-window'."
+Before running `org-tree-to-indirect-buffer', set
+`org-indirect-buffer-display' to `current-window'."
   (interactive "P")
   (let ((org-indirect-buffer-display 'current-window))
     (org-tree-to-indirect-buffer arg)))
@@ -227,8 +227,8 @@ The repeater is removed from the original subtree."
 
 (defun km/org-sort-parent (arg)
   "Sort on parent heading ARG levels up.
-After sorting, the point is returned to its previous location
-under the current heading."
+After sorting, return point to its previous location under the
+current heading."
   (interactive "p")
   (let ((heading (org-no-properties (org-get-heading t t)))
         (starting-pos (point))
@@ -437,7 +437,7 @@ A target is determined by `km/org-refile-dwim-target-file'."
 
 (defun km/org-refile-to-other-file (file &optional maxlevel)
   "Refile with `org-refile-targets' set to FILE.
-A numeric prefix can be given to set MAXLEVEL (defaults to 2)."
+A numeric prefix sets MAXLEVEL (defaults to 2)."
   (interactive "fFile: \nP")
   (let* ((maxlevel (prefix-numeric-value (or maxlevel 2)))
          (file (substring-no-properties file))
@@ -446,7 +446,7 @@ A numeric prefix can be given to set MAXLEVEL (defaults to 2)."
 
 (defun km/org-refile-to-other-org-buffer (buffer &optional maxlevel)
   "Refile with `org-refile-targets' set to BUFFER file name.
-A numeric prefix can be given to set MAXLEVEL (defaults to 2)."
+A numeric prefix sets MAXLEVEL (defaults to 2)."
   (interactive (list (km/get-org-file-buffer) current-prefix-arg))
   (let ((buffer-file (buffer-file-name buffer)))
     (km/org-refile-to-other-file buffer-file maxlevel)))
@@ -459,8 +459,7 @@ A numeric prefix can be given to set MAXLEVEL (defaults to 2)."
 (defun km/org-set-refiling-buffer (&optional maxlevel)
   "Choose buffer to set as sole target in `org-refile-targets'.
 If `org-refile-targets' is already a local variable, restore the
-global value. A numeric prefix can be given to set
-MAXLEVEL (defaults to 2)."
+global value. A numeric prefix sets MAXLEVEL (defaults to 2)."
   (interactive "P")
   (if (local-variable-p 'org-refile-targets)
       (kill-local-variable 'org-refile-targets)
diff --git a/lisp/init-python.el b/lisp/init-python.el
index 642e8fb..b16a005 100644
--- a/lisp/init-python.el
+++ b/lisp/init-python.el
@@ -22,7 +22,7 @@
 (defun km/find-python-test-file-other-window (arg)
   "Open test file for the current Python file in another window.
 If the file does not already exist, import the original Python
-file. Unless a ARG is non-nil, py.test is also imported."
+file. Unless ARG is non-nil, py.test is also imported."
   (interactive "P")
   (let* ((py-file (file-name-nondirectory buffer-file-name))
          (test-file (concat "test_" py-file)))
diff --git a/lisp/init-text.el b/lisp/init-text.el
index ca14174..2a4e3cd 100644
--- a/lisp/init-text.el
+++ b/lisp/init-text.el
@@ -5,11 +5,12 @@
 
 (defun km/export-wrapped-text (arg)
   "Export the text in current buffer as wrapped text.
+
 This is useful for preparing text in emacs and then exporting to
 a wrapped buffer for pasting text (e.g., into a web form).
 
-If region is active, export is restricted to the region. If ARG
-is non-nil, the region is copied with `x-select-text'."
+If region is active, restrict export to the region. If ARG is
+non-nil, copy the region with `x-select-text'."
   (interactive "P")
   (let ((wrapped-buffer (get-buffer-create "*Wrapped export*"))
         beg end)