docs: Fix checkdoc (#180)

* docs: Fix checkdoc

* update doc

* fix for subcommands

* fix for subcommands

lisp/checker/check-eask.el

@@ -43,7 +43,10 @@
         (lambda (elm) (string-prefix-p " *load*-" (buffer-name elm))) (buffer-list))))
 
 (defun eask--write-json-format (level msg)
-  "Prepare log for JSON format."
+  "Prepare log for JSON format.
+
+For arguments LEVEL and MSG, please see function `eask--write-log' for more
+information."
   (let* ((thing (thing-at-point 'sexp))
          (bounds (bounds-of-thing-at-point 'sexp))
          (filename (or load-file-name eask-file))
@@ -69,7 +72,10 @@
             (`warn  eask--checker-warnings)))))
 
 (defun eask--write-plain-text (level msg)
-  "Prepare log for plain text format."
+  "Prepare log for plain text format.
+
+For arguments LEVEL and MSG, please see function `eask--write-log' for more
+information."
   (let* ((level-string (cl-case level
                          (`error "Error")
                          (`warn  "Warning")))
@@ -82,7 +88,9 @@
     (push (ansi-color-filter-apply log) eask--checker-log)))
 
 (defun eask--write-log (level msg)
-  "Write the log."
+  "Write the log.
+
+Argument LEVEL and MSG are data from the debug log signal."
   (unless (string= " *temp*" (buffer-name))  ; avoid error from `package-file' directive
     (with-current-buffer (or (eask--load-buffer) (buffer-name))
       (funcall

lisp/clean/all.el

@@ -24,7 +24,7 @@
   "Count cleaning task.")
 
 (defvar eask--clean-tasks-cleaned 0
-  "Total cleaned tasks")
+  "Total cleaned tasks.")
 
 (defmacro eask--clean-section (title &rest body)
   "Print clean up TITLE and execute BODY."

lisp/core/archives.el

@@ -19,7 +19,7 @@
 (defvar eask--length-priority)
 
 (defun eask--print-archive (archive)
-  "Print the archive."
+  "Print the ARCHIVE."
   (let* ((name (car archive))
          (url (cdr archive))
          (priority (assoc name package-archive-priorities))

lisp/core/emacs.el

@@ -2,7 +2,7 @@
 
 ;;; Commentary:
 ;;
-;; Execute emacs with the appropriate environment
+;; Execute Emacs with the appropriate environment
 ;;
 ;;   $ eask emacs [args..]
 ;;

lisp/core/eval.el

@@ -2,7 +2,7 @@
 
 ;;; Commentary:
 ;;
-;; Evaluate lisp form with a proper PATH,
+;; Evaluate Lisp form with a proper PATH,
 ;;
 ;;   $ eask eval [form]
 ;;

lisp/core/exec.el

@@ -20,10 +20,10 @@
         nil t))
 
 (defconst eask--exec-path-file (expand-file-name "exec-path" eask-homedir)
-  "Target file to export the `exec-path' variable.")
+  "Target file to export the variable `exec-path'.")
 
 (defconst eask--load-path-file (expand-file-name "load-path" eask-homedir)
-  "Target file to export the `load-path' variable.")
+  "Target file to export the variable `load-path'.")
 
 (defun eask--export-env ()
   "Export environments."

lisp/core/info.el

@@ -17,7 +17,7 @@
 (defvar eask--max-offset 0)
 
 (defun eask--print-deps (title dependencies)
-  "Print dependencies."
+  "Print DEPENDENCIES with TITLE identifier."
   (when dependencies
     (eask-msg "")
     (eask-msg title)

lisp/core/install.el

@@ -24,7 +24,7 @@
 (eask-load "core/package")  ; load dist path
 
 (defun eask--install-packages (names)
-  "Install packages."
+  "Install packages with their NAMES."
   (let* ((names (mapcar #'eask-intern names))
          (len (length names)) (s (eask--sinr len "" "s"))
          (pkg-not-installed (cl-remove-if #'package-installed-p names))
@@ -40,6 +40,9 @@
 ;;
 ;; XXX: remove this after we drop 28.x
 (defun eask--package-install-file (file)
+  "Old compatible version of function `package-install-file'.
+
+For argument FILE, please see function `package-install-file' for the details."
   ;; Workaround: `package-install-file' fails when FILE is .el and contains CRLF EOLs:
   ;; https://debbugs.gnu.org/cgi/bugreport.cgi?bug=48137
   (if (not (string-match "\\.el\\'" file))

lisp/core/list.el

@@ -28,7 +28,10 @@
   (concat " %-" (number-to-string offset) "s "))
 
 (defun eask--align (depth &optional rest)
-  "Format string to align starting from the version number."
+  "Format string to align starting from the version number.
+
+Argument DEPTH is used to calculate the indentation.  REST is a list of string
+for string concatenation."
   (let ((prefix (if (= depth 0) "[+]" "[+]")))
     (concat (spaces-string (* depth 2))  ; indent for depth
             " " prefix
@@ -38,7 +41,11 @@
             rest)))
 
 (defun eask-print-pkg (name depth max-depth pkg-alist)
-  "Print NAME package information."
+  "Print NAME package information.
+
+Argument DEPTH is the current dependency nested level.  MAX-DEPTH is the
+limitation, so we don't go beyond this deepness.  PKG-ALIST is the archive
+contents."
   (when-let*
       ((pkg (assq name pkg-alist))
        (desc (cadr pkg))
@@ -56,19 +63,27 @@
         (eask-print-pkg (car req) (1+ depth) max-depth pkg-alist)))))
 
 (defun eask--version-list (pkg-alist)
-  "Return list of versions."
+  "Return a list of versions.
+
+PKG-ALIST is the archive contents."
   (mapcar (lambda (elm)
             (package-version-join (package-desc-version (cadr elm))))
           pkg-alist))
 
 (defun eask--archive-list (pkg-alist)
-  "Return list of archives."
+  "Return list of archives.
+
+PKG-ALIST is the archive contents."
   (mapcar (lambda (elm)
             (or (package-desc-archive (cadr elm)) ""))
           pkg-alist))
 
 (defun eask--list (list pkg-alist &optional depth)
-  "List packages."
+  "List packages.
+
+Argument LIST is the list of packages we want to list.  PKG-ALIST is the archive
+contents we want to retrieve package's metadate from.  Optional argument DEPTH
+is the deepness of the dependency nested level we want to go."
   (let* ((eask--list-pkg-name-offset (eask-seq-str-max list))
          (version-list (eask--version-list pkg-alist))
          (eask--list-pkg-version-offset (eask-seq-str-max version-list))

lisp/core/package.el

@@ -32,7 +32,9 @@
     package-build-default-files-spec))
 
 (defun eask-package-dir-recipe (version)
-  "Form a directory recipe."
+  "Form a directory recipe.
+
+Argument VERSION is a string represent the version number of this package."
   (eask-load "extern/package-recipe")
   (let* ((name (eask-guess-package-name))
          (patterns (eask-package-dir--patterns))
@@ -49,7 +51,7 @@
     (concat name "-" version)))
 
 (defun eask--packaged-file (ext)
-  "Find a possible packaged file."
+  "Find a possible packaged file with extension (EXT)."
   (expand-file-name (concat (eask-packaged-name) "." ext) eask-dist-path))
 
 (defun eask-packaged-file ()

lisp/core/reinstall.el

@@ -22,7 +22,7 @@
 (eask-load "core/package")  ; load dist path
 
 (defun eask--reinstall-packages (names)
-  "Install packages."
+  "Install packages by its NAMES."
   (let* ((names (mapcar #'eask-intern names))
          (len (length names)) (s (eask--sinr len "" "s"))
          (pkg-not-installed (cl-remove-if #'package-installed-p names))

lisp/core/run.el

@@ -41,7 +41,7 @@
   (write-region (concat command "\n") nil eask--run-file t))
 
 (defun eask--unmatched-scripts (scripts)
-  "Return a list of scripts that cannot be found in `eask-scripts'."
+  "Return a list of SCRIPTS that cannot be found in `eask-scripts'."
   (let (unmatched)
     (dolist (script scripts)
       (unless (assoc script eask-scripts)

lisp/core/uninstall.el

@@ -21,7 +21,7 @@
         nil t))
 
 (defun eask--uninstall-packages(names)
-  "Uninstall packages."
+  "Uninstall packages by its NAMES."
   (let* ((names (mapcar #'eask-intern names))
          (len (length names)) (s (eask--sinr len "" "s"))
          (pkg-installed (cl-remove-if-not #'package-installed-p names))

lisp/core/upgrade.el

@@ -20,7 +20,7 @@
         nil t))
 
 (defun eask--package-version-string (pkg-desc)
-  "Get package version string with color."
+  "Get package version string with color from PKG-DESC."
   (let ((version (package-desc-version pkg-desc)))
     (ansi-yellow (package-version-join version))))
 

lisp/generate/pkg-file.el

@@ -30,7 +30,7 @@
          (version (eask-package-version))
          (description (eask-package-description))
          (reqs (mapcar (lambda (elm)
-                         (list (if (stringp (car elm)) (intern (car elm)) (car elm))
+                         (list (eask-intern (car elm))
                                (if (= (length (cdr elm)) 1)
                                    (nth 0 (cdr elm))
                                  "0")))

lisp/link/add.el

@@ -33,7 +33,7 @@
 (defvar eask--link-package-version nil "Used to form package name.")
 
 (defun eask--create-link (name source)
-  "Add link with NAME to PATH."
+  "Add link with NAME to SOURCE path."
   (let* ((dir-name (format "%s-%s" eask--link-package-name eask--link-package-version))
          (link-path (expand-file-name dir-name package-user-dir)))
     (when (file-exists-p link-path)

lisp/lint/checkdoc.el

@@ -30,7 +30,10 @@
 (defvar eask--checkdoc-errors nil "Error flag.")
 
 (defun eask--checkdoc-print-error (text start end &optional unfixable)
-  "Print error for checkdoc."
+  "Print error for checkdoc.
+
+Arguments TEXT, START, END and UNFIXABLE are required for this function to
+be assigned to variable `checkdoc-create-error-function'."
   (setq eask--checkdoc-errors t)
   (let ((msg (concat (checkdoc-buffer-label) ":"
                      (int-to-string (count-lines (point-min) (or start (point-min))))

lisp/test/ert.el

@@ -21,21 +21,23 @@
 
 (require 'ert)
 
-(defvar ert--message-loop nil
+(defvar eask--message-loop nil
   "Prevent inifinite recursive message function.")
 
-(defun eask--ert-message (func &rest args)
-  "Colorized ert messages."
-  (if ert--message-loop (apply func args)
-    (let ((ert--message-loop t))
+(defun eask--ert-message (fnc &rest args)
+  "Colorized ert messages.
+
+Arguments FNC and ARGS are used for advice `:around'."
+  (if eask--message-loop (apply fnc args)
+    (let ((eask--message-loop t))
       (cond
        ((string-match-p "^[ ]+FAILED " (apply #'format args))
         (eask-msg (ansi-red (apply #'format args))))
        ((string-match-p "^[ ]+SKIPPED " (apply #'format args))
         (eask-msg (ansi-white (apply #'format args))))
        ((string-match-p "^[ ]+passed " (apply #'format args))
         (eask-msg (ansi-green (apply #'format args))))
-       (t (apply func args))))))
+       (t (apply fnc args))))))
 
 (advice-add 'message :around #'eask--ert-message)