v1.2.1 M-x checkdoc style changes.

updated many docstring. mostly minor changes.

zero-panel.el

@@ -25,7 +25,9 @@
 (require 's)
 
 (defun zero-panel-error-handler (event error)
-  "handle dbus errors"
+  "Handle dbus errors.
+
+EVENT and ERROR are error-handler arguments."
   (when (or (string-equal "com.emacsos.zero.Panel"
 			  (dbus-event-interface-name event))
 	    (s-contains-p "com.emacsos.zero.Panel" (cadr error)))
@@ -34,7 +36,10 @@
 (add-hook 'dbus-event-error-functions 'zero-panel-error-handler)
 
 (defun zero-panel-async-call (method _handler &rest args)
-  "call Method on zero-panel service asynchronously. This is a wrapper around `dbus-call-method-asynchronously'"
+  "Call METHOD on zero-panel service asynchronously.
+
+This is a wrapper around `dbus-call-method-asynchronously'.
+ARGS optional extra args to pass to the wrapped function."
   (apply 'dbus-call-method-asynchronously
 	 :session
 	 "com.emacsos.zero.Panel1"	; well known name
@@ -47,18 +52,18 @@
 ;;=========================
 
 (defun zero-alist-to-asv (hints)
-  "convert lisp alist to dbus a{sv} data structure.
-alist should be of form '((k1 [v1type] v1) (k2 [v2type] v2)).
+  "Convert Lisp alist to dbus a{sv} data structure.
+
+HINTS should be an alist of form '((k1 [v1type] v1) (k2 [v2type] v2)).
 
 For example,
-(zero-alist-to-asv
+\(zero-alist-to-asv
   '((\"name\" \"foo\")
     (\"timeout\" :int32 10)))
 =>
 '(:array
   (:dict-entry \"name\" (:variant \"foo\"))
-  (:dict-entry \"timeout\" (:variant :int32 10)))
-"
+  (:dict-entry \"timeout\" (:variant :int32 10)))"
   (if (null hints)
       '(:array :signature "{sv}")
     (let ((result '(:array)))
@@ -80,12 +85,14 @@ For example,
 ;;============
 
 (defun zero-panel-move (x y)
-  "move panel to specific position
-(x, y) are coordinates, (0, 0) is at screen top left corner"
+  "Move panel to specific coordinate (X, Y).
+Origin (0, 0) is at screen top left corner."
   (zero-panel-async-call "Move" nil :int32 x :int32 y))
 
 (defun zero-panel-show-candidates (preedit_str candidate_length candidates &optional hints)
-  "show candidates"
+  "Show CANDIDATES.
+Argument PREEDIT_STR the preedit string.
+Argument CANDIDATE_LENGTH how many candidates are in candidates list."
   (zero-panel-async-call "ShowCandidates" nil
 			 :string preedit_str
 			 :uint32 candidate_length
@@ -93,15 +100,15 @@ For example,
 			 (zero-alist-to-asv hints)))
 
 (defun zero-panel-show ()
-  "show panel"
+  "Show panel."
   (zero-panel-async-call "Show" nil))
 
 (defun zero-panel-hide ()
-  "hide panel"
+  "Hide panel."
   (zero-panel-async-call "Hide" nil))
 
 (defun zero-panel-quit ()
-  "quit panel application"
+  "Quit panel application."
   (interactive)
   (zero-panel-async-call "Quit" nil))
 

zero-pinyin-service.el

@@ -25,7 +25,7 @@
 (require 'cl-lib)
 
 (defun zero-pinyin-service-error-handler (event error)
-  "handle dbus errors"
+  "Handle dbus errors."
   (when (or (string-equal "com.emacsos.zero.ZeroPinyinService1"
 			  (dbus-event-interface-name event))
 	    (s-contains-p "com.emacsos.zero.ZeroPinyinService1" (cadr error)))
@@ -34,7 +34,10 @@
 (add-hook 'dbus-event-error-functions 'zero-pinyin-service-error-handler)
 
 (defun zero-pinyin-service-async-call (method handler &rest args)
-  "call Method on zero-pinin-service asynchronously. This is a wrapper around `dbus-call-method-asynchronously'"
+  "Call METHOD on zero-pinin-service asynchronously.
+This is a wrapper around `dbus-call-method-asynchronously'.
+Argument HANDLER the handler function.
+Optional argument ARGS extra arguments to pass to the wrapped function."
   (apply 'dbus-call-method-asynchronously
 	 :session "com.emacsos.zero.ZeroPinyinService1"
 	 "/com/emacsos/zero/ZeroPinyinService1"
@@ -42,7 +45,9 @@
 	 method handler :timeout 1000 args))
 
 (defun zero-pinyin-service-call (method &rest args)
-  "call Method on zero-pinin-service synchronously. This is a wrapper around `dbus-call-method'"
+  "Call METHOD on zero-pinin-service synchronously.
+This is a wrapper around `dbus-call-method'.
+Optional argument ARGS extra arguments to pass to the wrapped function."
   (apply 'dbus-call-method
 	 :session "com.emacsos.zero.ZeroPinyinService1"
 	 "/com/emacsos/zero/ZeroPinyinService1"
@@ -54,17 +59,18 @@
 ;;============
 
 (defun zero-pinyin-service-get-candidates (preedit-str fetch-size)
-  "get candidates for pinyin in preedit-str synchronously.
+  "Get candidates for pinyin in PREEDIT-STR synchronously.
 
 preedit-str the preedit-str, should be pure pinyin string
-fetch-size try to fetch this many candidates or more"
+FETCH-SIZE try to fetch this many candidates or more"
   (zero-pinyin-service-call "GetCandidates" :string preedit-str :uint32 fetch-size))
 
 (defun zero-pinyin-service-get-candidates-async (preedit-str fetch-size get-candidates-complete)
-  "get candidates for pinyin in preedit-str asynchronously.
+  "Get candidates for pinyin in PREEDIT-STR asynchronously.
 
-preedit-str the preedit-str, should be pure pinyin string
-fetch-size try to fetch this many candidates or more"
+PREEDIT-STR the preedit string, should be pure pinyin string.
+FETCH-SIZE try to fetch this many candidates or more.
+GET-CANDIDATES-COMPLETE the async handler function."
   (zero-pinyin-service-async-call
    "GetCandidates" get-candidates-complete :string preedit-str :uint32 fetch-size))
 
@@ -87,7 +93,7 @@ fetch-size try to fetch this many candidates or more"
 			  (:struct :int32 7 :int32 55)))))
 
 (defun zero-pinyin-service-commit-candidate-async (candidate candidate_pinyin_indices)
-  "commit candidate asynchronously"
+  "Commit CANDIDATE asynchronously."
   ;; don't care about the result, so no callback.
   (zero-pinyin-service-async-call
    "CommitCandidate" nil
@@ -95,12 +101,14 @@ fetch-size try to fetch this many candidates or more"
    (zero-pinyin-candidate-pinyin-indices-to-dbus-format candidate_pinyin_indices)))
 
 (defun zero-pinyin-service-delete-candidates-async (candidate delete-candidate-complete)
-  "delete candidate asynchronously"
+  "Delete CANDIDATE asynchronously.
+
+DELETE-CANDIDATE-COMPLETE the async handler function."
   (zero-pinyin-service-async-call
    "DeleteCandidate" delete-candidate-complete :string candidate))
 
 (defun zero-pinyin-service-quit ()
-  "quit panel application"
+  "Quit panel application."
   (zero-pinyin-service-async-call "Quit" nil))
 
 ;;================

zero-pinyin.el

@@ -15,7 +15,7 @@
 
 ;;; Commentary:
 
-;; use use this input method, add in emacs init file:
+;; To use this input method, add in Emacs init file:
 ;;
 ;;   (add-to-list 'load-path "~/fromsource/zero")
 ;;   (require 'zero-pinyin)
@@ -36,17 +36,17 @@
 ;; basic data and emacs facility
 ;;===============================
 
-(defvar zero-pinyin-state nil "zero-pinyin internal state. could be nil or `*zero-pinyin-state-im-partial-commit*'")
+(defvar zero-pinyin-state nil "zero-pinyin internal state. could be nil or `*zero-pinyin-state-im-partial-commit*'.")
 (defconst *zero-pinyin-state-im-partial-commit* 'IM-PARTIAL-COMMIT)
 
 (defvar zero-pinyin-used-preedit-str-lengths nil
-  "accompany `zero-candidates', marks how many preedit-str chars are used for each candidate")
+  "Accompany `zero-candidates', marks how many preedit-str chars are used for each candidate.")
 (defvar zero-pinyin-candidates-pinyin-indices nil
-  "store GetCandidates dbus method candidates_pinyin_indices field")
+  "Store GetCandidates dbus method candidates_pinyin_indices field.")
 (defvar zero-pinyin-pending-str "")
 (defvar zero-pinyin-pending-preedit-str "")
 (defvar zero-pinyin-pending-pinyin-indices nil
-  "stores `zero-pinyin-pending-str' corresponds pinyin indices")
+  "Stores `zero-pinyin-pending-str' corresponds pinyin indices.")
 
 ;;=====================
 ;; key logic functions
@@ -59,27 +59,27 @@
   (setq zero-pinyin-pending-preedit-str ""))
 
 (defun zero-pinyin-init ()
-  "called when this im is turned on"
+  "Called when this im is turned on."
   (make-local-variable 'zero-pinyin-state)
   (zero-pinyin-reset))
 
 (defun zero-pinyin-preedit-start ()
-  "called when enter `*zero-state-im-preediting*' state"
+  "Called when enter `*zero-state-im-preediting*' state."
   (define-key zero-mode-map [remap digit-argument] 'zero-digit-argument))
 
 (defun zero-pinyin-preedit-end ()
-  "called when leave `*zero-state-im-preediting*' state"
+  "Called when leave `*zero-state-im-preediting*' state."
   (define-key zero-mode-map [remap digit-argument] nil))
 
 (defun zero-pinyin-shutdown ()
-  "called when this im is turned off"
+  "Called when this im is turned off."
   (define-key zero-mode-map [remap digit-argument] nil))
 
 (defvar zero-pinyin--build-candidates-use-test-data nil
-  "if t, `zero-pinyin-build-candidates' will use `zero-pinyin-build-candidates-test'")
+  "If t, `zero-pinyin-build-candidates' will use `zero-pinyin-build-candidates-test'.")
 
 (defun zero-pinyin-build-candidates (preedit-str fetch-size)
-  "zero-pinyin-build-candidates synchronous version"
+  "zero-pinyin-build-candidates synchronous version."
   (if zero-pinyin--build-candidates-use-test-data
       (progn
 	(zero-pinyin-build-candidates-test preedit-str)
@@ -92,7 +92,7 @@
       (cl-first result))))
 
 (defun zero-pinyin-build-candidates-async (preedit-str fetch-size complete-func)
-  "build candidate list, when done call complete-func on it"
+  "Build candidate list, when done call complete-func on it."
   (zero-debug "zero-pinyin building candidate list asynchronously\n")
   (zero-pinyin-service-get-candidates-async
    preedit-str
@@ -106,7 +106,7 @@
      (funcall complete-func candidates))))
 
 (defun zero-pinyin-can-start-sequence (ch)
-  "return t if char ch can start a preedit sequence."
+  "Return t if char CH can start a preedit sequence."
   (and (>= ch ?a)
        (<= ch ?z)
        (not (= ch ?i))
@@ -130,7 +130,7 @@
   (zero-pinyin-build-candidates-async zero-pinyin-pending-preedit-str zero-initial-fetch-size 'zero-build-candidates-complete))
 
 (defun zero-pinyin-commit-nth-candidate (n)
-  "commit nth candidate and return true if it exists, otherwise, return false"
+  "Commit Nth candidate and return true if it exists, otherwise, return false."
   (let* ((n-prime (+ n (* zero-candidates-per-page zero-current-page)))
 	 (candidate (nth n-prime zero-candidates))
 	 (used-len (when candidate
@@ -188,8 +188,8 @@
     (zero-commit-preedit-str)))
 
 (defun zero-pinyin-commit-first-candidate-in-full ()
-  "commit first candidate and return t if first candidate consumes all preedit-str.
-otherwise, just return nil"
+  "Commit first candidate and return t if it consumes all preedit-str.
+Otherwise, just return nil."
   (let ((candidate (nth 0 (zero-candidates-on-page zero-candidates)))
 	(used-len (nth (* zero-candidates-per-page zero-current-page) zero-pinyin-used-preedit-str-lengths)))
     (when candidate
@@ -208,7 +208,7 @@ otherwise, just return nil"
        (t (error "Unexpected zero-pinyin-state: %s" zero-pinyin-state))))))
 
 (defun zero-pinyin-page-down ()
-  "handle page down for zero-pinyin.
+  "Handle page down for zero-pinyin.
 
 This is different from zero-framework because I need to support partial commit"
   (let ((len (length zero-candidates))
@@ -225,7 +225,8 @@ This is different from zero-framework because I need to support partial commit"
       (zero-just-page-down))))
 
 (defun zero-pinyin-handle-preedit-char (ch)
-  "hanlde character insert in `*zero-state-im-preediting*' state. overrides `zero-handle-preedit-char-default'"
+  "Hanlde character insert in `*zero-state-im-preediting*' state.
+Override `zero-handle-preedit-char-default'."
   (cond
    ((= ch ?\s)
     (zero-pinyin-commit-first-candidate-or-preedit-str))
@@ -255,23 +256,24 @@ This is different from zero-framework because I need to support partial commit"
     zero-preedit-str))
 
 (defun zero-pinyin-preedit-str-changed ()
-  "start over for candidate selection process."
+  "Start over for candidate selection process."
   (setq zero-pinyin-state nil)
   (zero-preedit-str-changed))
 
 (defun zero-pinyin-backspace ()
-  "handle backspace key in `*zero-state-im-preediting*' state"
+  "Handle backspace key in `*zero-state-im-preediting*' state."
   (if (eq zero-pinyin-state *zero-pinyin-state-im-partial-commit*)
       (zero-pinyin-preedit-str-changed)
     (zero-backspace-default)))
 
 (defun zero-pinyin-delete-candidate (digit)
-  "tell backend to delete nth candidate.
+  "Tell backend to delete candidate at DIGIT position.
 
-n is the digit selection number.
-1 means delete 1st candidate.
-2 means delete 2st candidate.
-0 means delete 10th candidate."
+DIGIT is the digit key used to select nth candidate.
+DIGIT 1 means delete 1st candidate.
+DIGIT 2 means delete 2st candidate.
+...
+DIGIT 0 means delete 10th candidate."
   (let ((candidate (nth (mod (- digit 1) 10)
 			(zero-candidates-on-page zero-candidates))))
     (when candidate
@@ -279,7 +281,7 @@ n is the digit selection number.
        candidate 'zero-pinyin-preedit-str-changed))))
 
 (defun zero-digit-argument ()
-  "allow C-<digit> to DeleteCandidate in `*zero-state-im-preediting*' state"
+  "Allow C-<digit> to DeleteCandidate in `*zero-state-im-preediting*' state."
   (interactive)
   (unless (eq zero-state *zero-state-im-preediting*)
     (error "zero-digit-argument called in non preediting state"))
@@ -317,7 +319,9 @@ n is the digit selection number.
 ;;===========
 
 (defun zero-pinyin-build-candidates-test (preedit-str)
-  "test data for testing partial commit"
+  "Test data for testing partial commit.
+
+PREEDIT-STR the preedit string."
   (cond
    ((equal preedit-str "liyifeng")
     (setq zero-pinyin-used-preedit-str-lengths '(8 4 4 4 2 2 2))

zero-quickdial.el

@@ -22,7 +22,7 @@
 ;; type 3 will insert three.
 ;; M-x zero-quickdial-mode    ; turn off IM
 ;;
-;; This is just a demo of how emacs minor mode can work as input method.
+;; This is just a demo of how Emacs minor mode can work as input method.
 
 ;;; Code:
 
@@ -43,7 +43,7 @@
     (49 . zero-quickdial-insert-one)
     (50 . zero-quickdial-insert-two)
     (51 . zero-quickdial-insert-three))
-  "zero-quickdial-mode keymap")
+  "zero-quickdial-mode keymap.")
 
 (define-minor-mode zero-quickdial-mode
   "a simple input method written as an emacs minor mode"

zero-table.el

@@ -37,16 +37,15 @@
 ;; basic data and emacs facility
 ;;===============================
 
-(defvar zero-table-table nil "zero-table's table, map string to string")
-(defvar zero-table-sequence-initials nil "used in `zero-table-can-start-sequence'")
+(defvar zero-table-table nil "zero-table's table, map string to string.")
+(defvar zero-table-sequence-initials nil "Used in `zero-table-can-start-sequence'.")
 
 ;;=====================
 ;; key logic functions
 ;;=====================
 
 (defun zero-table-sort-key (lhs rhs)
-  "a predicate function to sort candidates. return t if lhs
-should sort before rhs."
+  "A predicate function to sort candidates.  Return t if LHS should sort before RHS."
   (string< (car lhs) (car rhs)))
 
 (defun zero-table-build-candidates (preedit-str &optional _fetch-size)
@@ -67,7 +66,7 @@ should sort before rhs."
 ;;     (zero-table-show-candidates candidates)))
 
 (defun zero-table-can-start-sequence (ch)
-  "return t if char ch can start a preedit sequence."
+  "Return t if char CH can start a preedit sequence."
   (member (make-string 1 ch) zero-table-sequence-initials))
 
 (ert-deftest zero-table-can-start-sequence ()
@@ -90,18 +89,17 @@ should sort before rhs."
 ;;============
 
 (defun zero-table-set-table (alist)
-  "set the conversion table.
+  "Set the conversion table.
 
-the alist should be a list of (key . value) pairs. when user type
-(part of) key, the IM will show all matching value.
+the ALIST should be a list of (key . value) pairs.  when user type
+\(part of) key, the IM will show all matching value.
 
 e.g.
 '((\"phone\" . \"18612345678\")
   (\"mail\" . \"foo@example.com\")
   (\"map\" . \"https://ditu.amap.com/\")
   (\"m\" . \"https://msdn.microsoft.com/en-us\")
-  (\"address\" . \"123 Happy Street\"))
-"
+  (\"address\" . \"123 Happy Street\"))"
   (setq zero-table-table alist)
   (setq zero-table-sequence-initials
 	(delete-dups (mapcar (lambda (pair) (substring (car pair) 0 1))