[nongnu] elpa/evil-nerd-commenter cb96ce729f 125/235: complete doc. make `M-x checkdoc' happy

[ELPA Syncer]

branch: elpa/evil-nerd-commenter
commit cb96ce729fe1f5bbfae59be10c4b7ddd086fbc2e
Author: Chen Bin <chenbin.sh@gmail.com>
Commit: Chen Bin <chenbin.sh@gmail.com>

    complete doc. make `M-x checkdoc' happy
---
 evil-nerd-commenter.el | 126 +++++++++++++++++++++++++++++--------------------
 1 file changed, 76 insertions(+), 50 deletions(-)

diff --git a/evil-nerd-commenter.el b/evil-nerd-commenter.el
index e510d48bb2..a7667e0dcf 100644
--- a/evil-nerd-commenter.el
+++ b/evil-nerd-commenter.el
@@ -11,8 +11,8 @@
 
 ;;; Credits:
 
-;; - Lally Oppenheimer (AKA lalopmak, https://github.com/lalopmak) added the 
support for text-object in Evil
-;; - Tom Willemse (AKA ryuslash, https://github.com/ryuslash) provided the fix 
to make Emacs 24.4 work
+;; - Lally Oppenheimer added the support for text-object in Evil
+;; - Tom Willemse provided the fix to make Emacs 24.4 work
 
 ;;; License:
 
@@ -36,38 +36,38 @@
 ;;
 ;; This program emulates nerd-commenter.vim by Marty Grenfell.
 ;;
-;; It help you comment/uncomment multiple lines without selecting them.
+;; It helps you comment/uncomment multiple lines without selecting them.
 ;;
 ;; `M-x evilnc-default-hotkeys` assigns hotkey `M-;` to 
`evilnc-comment-or-uncomment-lines`
 ;;
 ;; `M-x evilnc-comment-or-uncomment-lines` comment or uncomment lines.
 ;;
-;; `M-x evilnc-quick-comment-or-uncomment-to-the-line` will comment/uncomment 
from current line to
-;; the specified line number. The last digit(s) of line number is parameter of 
the command.
+;; `M-x evilnc-quick-comment-or-uncomment-to-the-line` will comment/uncomment
+;; from current line to specified line.
+;; The last digit(s) of line number is parameter of the command.
 ;;
-;; For example, `C-u 9 evilnc-quick-comment-or-uncomment-to-the-line` will 
comment code from
-;; current line to line 99 if you current line is 91.
+;; For example, `C-u 9 evilnc-quick-comment-or-uncomment-to-the-line` comments
+;; code from current line to line 99 if you current line is 91.
 ;;
-;; Though this program could be used *independently*, I highly recommend you 
use it with
-;; evil (http://gitorious.org/evil)
+;; Though this program could be used *independently*, though I highly recommend
+;; using it with Evil (http://gitorious.org/evil)
 ;;
-;; Evil makes you take advantage of power of Vi to comment lines in shocking 
speed.
+;; Evil makes you take advantage of power of Vi to comment lines.
 ;; For example, you can press key `99,ci` to comment out 99 lines.
 ;;
 ;; Setup:
 ;;
 ;; Check https://github.com/redguardtoo/evil-nerd-commenter for more use cases.
 ;;
-;; Use case 1, If you use comma as leader key, as most Vim users do, setup is 
just one liner,
+;; Use case 1,
+;; If you use comma as leader key, as most Vim users do, setup is one liner,
 ;; (evilnc-default-hotkeys)
 ;;
-;; Use case 2, If you are using evil-leader and didn't change the whose 
default leader key,
+;; Use case 2,
+;; If you use evil-leader and its default leader key,
 ;; insert below setup into your ~/.emacs instead,
 ;;
 ;; (global-set-key (kbd "M-;") 'evilnc-comment-or-uncomment-lines)
-;; (global-set-key (kbd "C-c l") 
'evilnc-quick-comment-or-uncomment-to-the-line)
-;; (global-set-key (kbd "C-c c") 'evilnc-copy-and-comment-lines)
-;; (global-set-key (kbd "C-c p") 'evilnc-comment-or-uncomment-paragraphs)
 ;;
 ;; (require 'evil-leader)
 ;; (global-evil-leader-mode)
@@ -88,25 +88,26 @@
   "If t then invert region comment status line by line.
 Please note it has NOT effect on evil text object!")
 
-;; shamelessly copied from goto-line
-(defun evilnc--goto-line (line)
+(defun evilnc--goto-line (line-num)
+  "Shamelessly copied from `goto-line'.  Goto line with LINE-NUM."
   (save-restriction
     (widen)
     (goto-char (point-min))
     (if (eq selective-display t)
-      (re-search-forward "[\n\C-m]" nil 'end (1- line))
-      (forward-line (1- line)))))
+      (re-search-forward "[\n\C-m]" nil 'end (1- line-num))
+      (forward-line (1- line-num)))))
 
-;; Since web-mode changes, the best way is to replace it with my own API
 (defun evilnc--web-mode-is-comment (&optional pos)
+  "Since `web-mode' remote the API we use, we have to create our own.
+Check whether the code at POS is comment."
   (unless pos (setq pos (point)))
   (not (null (or (eq (get-text-property pos 'tag-type) 'comment)
                  (eq (get-text-property pos 'block-token) 'comment)
                  (eq (get-text-property pos 'part-token) 'comment)))))
 
 (defun evilnc--fix-buggy-major-modes ()
-  "fix major modes whose comment regex is buggy.
-@see http://lists.gnu.org/archive/html/bug-gnu-emacs/2013-03/msg00891.html";
+  "Fix major modes whose comment regex is buggy.
+See http://lists.gnu.org/archive/html/bug-gnu-emacs/2013-03/msg00891.html.";
   (if (eq major-mode 'autoconf-mode)
     ;; since comment-use-syntax is nil in autoconf.el, the comment-start-skip 
need
     ;; make sure its first parenthesized expression match the string exactly 
before
@@ -121,18 +122,20 @@ Please note it has NOT effect on evil text object!")
         ;; Maybe autoconf.el will (setq comment-use-syntax t) in the future?
         (setq comment-start-skip "^\\(\\s*\\)\\(dnl\\|#\\) +"))))
 
-(defun evilnc--operation-on-lines-or-region (fn &optional NUM)
+(defun evilnc--operation-on-lines-or-region (fn &optional num)
+  "Apply FN on NUM lines or selected region."
   (cond
+   ;; NO region is selected
    ((not (region-active-p))
     (let ((b (line-beginning-position)) e)
       (save-excursion
-        (forward-line (- NUM 1))
-        (setq e (line-end-position))
-        )
+        (forward-line (- num 1))
+        (setq e (line-end-position)))
       (funcall fn b e)))
+
+   ;; Select region inside ONE line
    ((and (<= (line-beginning-position) (region-beginning))
           (<= (region-end) (line-end-position)))
-    ;; Select region inside ONE line
     (cond
      ;; Well, looks current comment syntax is NOT fit for comment out a region.
      ;; So we also need hack the comment-start and comment-end
@@ -164,6 +167,8 @@ Please note it has NOT effect on evil text object!")
         (setq comment-end-skip comment-end-skip-old)))
      ;; just comment out the region
      (t (funcall fn (region-beginning) (region-end)))))
+
+   ;; Select more than one line
    (t
     ;; selected region spans MORE than one line
     (save-excursion
@@ -187,6 +192,7 @@ Please note it has NOT effect on evil text object!")
    ))
 
 (defun evilnc--get-one-paragraph-region ()
+  "Select a paragraph which has NO empty line."
   (let (b e)
     (save-excursion
       (setq b (re-search-backward "^[ \t]*$" nil t))
@@ -209,6 +215,7 @@ Please note it has NOT effect on evil text object!")
     ))
 
 (defun evilnc--in-comment-p (pos)
+  "Check whether the code at POS is comment by comparing font face."
   (interactive)
   (let ((fontfaces (get-text-property pos 'face)))
     (when (not (listp fontfaces))
@@ -220,8 +227,8 @@ Please note it has NOT effect on evil text object!")
                           (eq f 'font-lock-comment-delimiter-face)))
                   fontfaces))))
 
-;; @return (list beg end)
 (defun evilnc--extend-to-whole-comment (beg end)
+  "Extend the comment region defined by BEG and END so ALL comment is 
included."
   (interactive)
   (if (evilnc--in-comment-p beg)
       (save-excursion
@@ -250,7 +257,7 @@ Please note it has NOT effect on evil text object!")
     ))
 
 (defun evilnc--invert-comment (beg end)
-  "Scan the region line by line, invert its comment status"
+  "Scan the region from BEG to END line by line, invert its comment status."
   (let (done b e)
     (save-excursion
       (goto-char end)
@@ -272,6 +279,8 @@ Please note it has NOT effect on evil text object!")
         ))))
 
 (defun evilnc--working-on-region (beg end fn)
+  "Region from BEG to END is applied with operation FN.
+Code snippets embedded in Org-mode is identified and right `major-mode' is 
used."
   (let (pos
         info
         lang
@@ -311,6 +320,7 @@ Please note it has NOT effect on evil text object!")
     ))
 
 (defun evilnc--comment-or-uncomment-region (beg end)
+  "Comment or uncommment region from BEG to END."
   (cond
    ((eq major-mode 'web-mode)
     ;; web-mode comment only works when region selected
@@ -344,6 +354,7 @@ Please note it has NOT effect on evil text object!")
     ))
 
 (defun evilnc--current-line-num ()
+  "Get current line number."
   (save-restriction
     (widen)
     (save-excursion
@@ -351,6 +362,9 @@ Please note it has NOT effect on evil text object!")
       (1+ (count-lines 1 (point))))))
 
 (defun evilnc--find-dst-line-num (UNITS)
+  "Find closet line whose line number ends with digit UNITS.
+Given UNITS as 5, line 5, line 15, and line 25 are good candidates.
+If UNITS is 16, line 16, line 116, and line 216 are good candidates."
   (let ((cur-line-num (evilnc--current-line-num))
         dst-line-num
         (r 1)
@@ -368,7 +382,8 @@ Please note it has NOT effect on evil text object!")
 
 ;;;###autoload
 (defun evilnc-comment-or-uncomment-paragraphs (&optional NUM)
-  "Comment or uncomment paragraph(s). A paragraph is a continuation non-empty 
lines.
+  "Comment or uncomment NUM paragraph(s).
+A paragraph is a continuation non-empty lines.
 Paragraphs are separated by empty lines."
   (interactive "p")
   (let ((i 0)
@@ -408,7 +423,7 @@ Paragraphs are separated by empty lines."
 
 ;;;###autoload
 (defun evilnc-comment-or-uncomment-to-the-line (&optional LINENUM)
-  "Comment or uncomment from the current line to the LINENUM line"
+  "Comment or uncomment from current line to LINENUM line."
   (interactive "nLine: ")
   (if (not (region-active-p))
       (let ((b (line-beginning-position))
@@ -425,9 +440,11 @@ Paragraphs are separated by empty lines."
 
 ;;;###autoload
 (defun evilnc-quick-comment-or-uncomment-to-the-line (&optional UNITS)
-  "Comment or uncomment to line number by specifying its last digit(s)
-For exmaple, you can use 'C-u 53 M-x 
evilnc-quick-comment-or-uncomment-to-the-line'
-or 'C-u 3 M-x evilnc-quick-comment-or-uncomment-to-the-line' to comment to the 
line 6453"
+  "Comment/uncomment to line number by last digit(s) whose value is UNITS.
+For exmaple, you can use either \
+\\<M-53>\\[evilnc-quick-comment-or-uncomment-to-the-line] \
+or \\<M-3>\\[evilnc-quick-comment-or-uncomment-to-the-line] \
+to comment to the line 6453"
   (interactive "p")
   (let ((dst-line-num (evilnc--find-dst-line-num UNITS)))
     (evilnc-comment-or-uncomment-to-the-line dst-line-num)
@@ -436,7 +453,7 @@ or 'C-u 3 M-x 
evilnc-quick-comment-or-uncomment-to-the-line' to comment to the l
 
 ;;;###autoload
 (defun evilnc-toggle-invert-comment-line-by-line ()
-  "Please note this command may NOT work on complex evil text objects"
+  "Please note this command may NOT work on complex evil text objects."
   (interactive)
   (if evilnc-invert-comment-line-by-line
       (setq evilnc-invert-comment-line-by-line nil)
@@ -448,6 +465,7 @@ or 'C-u 3 M-x 
evilnc-quick-comment-or-uncomment-to-the-line' to comment to the l
 
 ;;;###autoload
 (defun evilnc-toggle-comment-empty-lines ()
+  "Toggle the flag which decide wether empty line will be commented."
   (interactive)
   (if comment-empty-lines
       (setq comment-empty-lines nil)
@@ -459,13 +477,17 @@ or 'C-u 3 M-x 
evilnc-quick-comment-or-uncomment-to-the-line' to comment to the l
 
 ;;;###autoload
 (defun evilnc-comment-or-uncomment-lines (&optional NUM)
-  "Comment or uncomment NUM lines. NUM could be negative.
-   Case 1: If no region selected, comment/uncomment on current line. if NUM>1, 
comment/uncomment
-   extra N-1 lines from next line
-   Case 2: If a region selected, the region is expand to make sure the region 
contain
-   whole lines. Then we comment/uncomment the expanded region. NUM is ignored.
-   Case 3: If a region in ONE line is selected, we comment/uncomment that 
region.
-   In this case, CORRECT comment syntax will be used for C++/Java/Javascript."
+  "Comment or uncomment NUM lines.  NUM could be negative.
+
+Case 1: If no region selected, comment/uncomment on current line.
+If NUM>1, comment/uncomment extra N-1 lines from next line.
+
+Case 2: Selected region is expanded to make it contain whole lines.
+Then we comment/uncomment the expanded region.  NUM is ignored.
+
+Case 3: If a region inside of ONE line is selected,
+we comment/uncomment that region.
+CORRECT comment syntax will be used for C++/Java/Javascript."
   (interactive "p")
   ;; donot move the cursor
   ;; support negative number
@@ -486,11 +508,14 @@ or 'C-u 3 M-x 
evilnc-quick-comment-or-uncomment-to-the-line' to comment to the l
 
 ;;;###autoload
 (defun evilnc-copy-and-comment-lines (&optional NUM)
-  "Copy and paste NUM lines. Then comment the original lines. NUM could be 
negative.
-   Case 1: If no region selected, operate on current line. if NUM>1, 
comment/uncomment
-   extra N-1 lines from next line
-   Case 2: If a region selected, the region is expand to make sure the region 
contain
-   whole lines. Then we operate the expanded region. NUM is ignored."
+  "Copy&paste NUM lines and comment out original lines.
+NUM could be negative.
+
+Case 1: If no region selected, operate on current line.
+if NUM>1, comment/uncomment extra N-1 lines from next line
+
+Case 2: Selected region is expanded to make it contain whole lines.
+Then we operate the expanded region.  NUM is ignored."
   (interactive "p")
   ;; support negative number
   (when (< NUM 0)
@@ -511,7 +536,7 @@ or 'C-u 3 M-x 
evilnc-quick-comment-or-uncomment-to-the-line' to comment to the l
 ;; {{ for non-evil user only
 ;;;###autoload
 (defun evilnc-copy-to-line (&optional LINENUM)
-  "Copy from the current line to the LINENUM line, for non-evil user only"
+  "Copy from the current line to LINENUM line.  For non-evil user only."
   (interactive "nCopy to line: ")
   (if (not (region-active-p))
       (let ((b (line-beginning-position))
@@ -527,7 +552,7 @@ or 'C-u 3 M-x 
evilnc-quick-comment-or-uncomment-to-the-line' to comment to the l
 
 ;;;###autoload
 (defun evilnc-kill-to-line (&optional LINENUM)
-  "Kill from the current line to the LINENUM line, for non-evil user only"
+  "Kill from the current line to the LINENUM line.  For non-evil user only."
   (interactive "NKill to line: ")
   (if (not (region-active-p))
       (let ((b (line-beginning-position))
@@ -546,12 +571,13 @@ or 'C-u 3 M-x 
evilnc-quick-comment-or-uncomment-to-the-line' to comment to the l
 
 ;;;###autoload
 (defun evilnc-version ()
+  "The version number."
   (interactive)
   (message "2.0"))
 
 ;;;###autoload
 (defun evilnc-default-hotkeys ()
-  "Set the hotkeys of evil-nerd-comment"
+  "Set the hotkeys of evil-nerd-comment."
   (interactive)
 
   ;; Install hotkeys for Emacs mode