Documentation improvements

Reported by checkdoc

10 files changed, 51 insertions, 29 deletions

diff --git a/ledger-check.el b/ledger-check.el
index e20ac51..a0c3305 100644
--- a/ledger-check.el
+++ b/ledger-check.el
@@ -110,7 +110,10 @@
   (kill-buffer (get-buffer ledger-check-buffer-name)))
 
 (defun ledger-check-buffer ()
-  "Run ledge with --explicit and --strict report errors and assist with fixing them.
+  "Check the current buffer for errors.
+
+Runs ledger with --explicit and --strict report errors and assist
+with fixing them.
 
 The output buffer will be in `ledger-check-mode', which defines
 commands for navigating the buffer to the errors found, etc."
@@ -136,3 +139,5 @@ commands for navigating the buffer to the errors found, etc."
 
 
 (provide 'ledger-check)
+
+;;; ledger-check.el ends here
diff --git a/ledger-commodities.el b/ledger-commodities.el
index beb4759..50453dc 100644
--- a/ledger-commodities.el
+++ b/ledger-commodities.el
@@ -110,7 +110,11 @@ Returns a list with (value commodity)."
   (replace-regexp-in-string char "" str))
 
 (defun ledger-string-to-number (str &optional decimal-comma)
-  "improve builtin string-to-number by handling internationalization, and return nil if number can't be parsed"
+  "Parse STR as a number and return that number.
+
+Improves builtin `string-to-number' by handling
+internationalization, and return nil if number can't be parsed.
+See `ledger-environment-alist' for DECIMAL-COMMA."
   (let ((nstr (if (or decimal-comma
                       (assoc "decimal-comma" ledger-environment-alist))
                   (ledger-strip str "[.]")
@@ -120,7 +124,8 @@ Returns a list with (value commodity)."
     (string-to-number nstr)))
 
 (defun ledger-number-to-string (n &optional decimal-comma)
-  "number-to-string that handles comma as decimal."
+  "See `number-to-string' for N.
+DECIMAL-COMMA is as documented in `ledger-environment-alist'."
   (let ((str (number-to-string n)))
     (when (or decimal-comma
               (assoc "decimal-comma" ledger-environment-alist))
diff --git a/ledger-context.el b/ledger-context.el
index 0a225c5..5400727 100644
--- a/ledger-context.el
+++ b/ledger-context.el
@@ -53,7 +53,7 @@
   (concat (apply 'concat (mapcar 'ledger-get-regex-str elements)) "[ \t]*$"))
 
 (defmacro ledger-single-line-config (&rest elements)
-  "Take list of ELEMENTS and return regex and element list for use in context-at-point"
+  "Take list of ELEMENTS and return regex and element list for use in context-at-point."
   `(list (ledger-line-regex (quote ,elements)) (quote ,elements)))
 
 (defconst ledger-line-config
diff --git a/ledger-fonts.el b/ledger-fonts.el
index 4963e17..b4f9a7b 100644
--- a/ledger-fonts.el
+++ b/ledger-fonts.el
@@ -457,7 +457,7 @@ UNCLEARED otherwise."
   "Construct anchored highlighters for subdirectives.
 
 Each element of SUBDIRECTIVES should have the form (MATCHER
-SUBEXP-HIGHLIGHTERS…). The result will be a list of elements of
+SUBEXP-HIGHLIGHTERS…).  The result will be a list of elements of
 the form (MATCHER PRE-FORM POST-FORM SUBEXP-HIGHLIGHTERS) with
 PRE-FORM and POST-FORM set to appropriate values.
 
diff --git a/ledger-mode.el b/ledger-mode.el
index bdd1b5e..0e3a305 100644
--- a/ledger-mode.el
+++ b/ledger-mode.el
@@ -101,16 +101,14 @@
                         (org-read-date nil t nil prompt))))
 
 (defun ledger-get-minibuffer-prompt (prompt default)
-  "Return a string composing of PROMPT and DEFAULT appropriate
-for a minibuffer prompt."
+  "Return a string composing of PROMPT and DEFAULT appropriate for a minibuffer prompt."
   (concat prompt
           (if default
               (concat " (" default "): ")
             ": ")))
 
 (defun ledger-completing-read-with-default (prompt default collection)
-  "Return a user supplied string after PROMPT, or DEFAULT while
-  providing completions from COLLECTION."
+  "Return a user supplied string after PROMPT, or DEFAULT while providing completions from COLLECTION."
   (completing-read (ledger-get-minibuffer-prompt prompt default)
                    collection nil nil nil 'ledger-minibuffer-history default))
 
@@ -123,7 +121,7 @@ for a minibuffer prompt."
   "Display the cleared-or-pending balance.
 And calculate the target-delta of the account being reconciled.
 
-With prefix argument \\[universal-argument] ask for the target commodity and convert
+With ARG (\\[universal-argument]) ask for the target commodity and convert
 the balance into that."
   (interactive "P")
   (let* ((account (ledger-read-account-with-prompt "Account balance to show"))
diff --git a/ledger-reconcile.el b/ledger-reconcile.el
index 4522b21..2b25b91 100644
--- a/ledger-reconcile.el
+++ b/ledger-reconcile.el
@@ -59,8 +59,9 @@
   :group 'ledger-reconcile)
 
 (defcustom ledger-buffer-tracks-reconcile-buffer t
-  "If t, then when the cursor is moved to a new transaction in the reconcile buffer.
-Then that transaction will be shown in its source buffer."
+  "If t, move point in the ledger buffer when it moves in the reconcile buffer.
+When the cursor is moved to a new transaction in the reconcile
+buffer then that transaction will be shown in its source buffer."
   :type 'boolean
   :group 'ledger-reconcile)
 
@@ -77,7 +78,7 @@ reconcile-finish will mark all pending posting cleared."
 
 (defcustom ledger-reconcile-default-date-format ledger-default-date-format
   "Date format for the reconcile buffer.
-Default is ledger-default-date-format."
+Default is `ledger-default-date-format'."
   :type 'string
   :group 'ledger-reconcile)
 
@@ -101,8 +102,8 @@ amount.  The format for each field is %WIDTH(FIELD), WIDTH can be
 preced by a minus sign which mean to left justify and pad the
 field.  WIDTH is the minimum number of characters to display;
 if string is longer, it is not truncated unless
-ledger-reconcile-buffer-payee-max-chars or
-ledger-reconcile-buffer-account-max-chars is defined."
+`ledger-reconcile-buffer-payee-max-chars' or
+`ledger-reconcile-buffer-account-max-chars' is defined."
   :type 'string
   :group 'ledger-reconcile)
 
@@ -511,14 +512,14 @@ moved and recentered.  If they aren't strange things happen."
     (pop-to-buffer rbuf)))
 
 (defun ledger-reconcile-check-valid-account (account)
-  "Check to see if ACCOUNT exists in the ledger file"
+  "Check to see if ACCOUNT exists in the ledger file."
   (if (> (length account) 0)
       (save-excursion
         (goto-char (point-min))
         (search-forward account nil t))))
 
 (defun ledger-reconcile (&optional account target)
-  "Start reconciling, prompt for account."
+  "Start reconciling, prompt for ACCOUNT."
   (interactive)
   (let ((account (or account (ledger-read-account-with-prompt "Account to reconcile")))
         (buf (current-buffer))
@@ -560,7 +561,7 @@ moved and recentered.  If they aren't strange things happen."
 (defvar ledger-reconcile-mode-abbrev-table)
 
 (defun ledger-reconcile-change-target (&optional target)
-  "Change the target amount for the reconciliation process."
+  "Change the TARGET amount for the reconciliation process."
   (interactive)
   (setq ledger-target (or target (ledger-read-commodity-string ledger-reconcile-target-prompt-string))))
 
diff --git a/ledger-regex.el b/ledger-regex.el
index 8ac3002..ab8f752 100644
--- a/ledger-regex.el
+++ b/ledger-regex.el
@@ -19,6 +19,12 @@
 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
 ;; MA 02110-1301 USA.
 
+
+;;; Commentary:
+;; Regular expressions used by ledger-mode.
+
+;;; Code:
+
 (require 'rx)
 (require 'cl-lib)
 
@@ -404,3 +410,5 @@
 
 
 (provide 'ledger-regex)
+
+;;; ledger-regex.el ends here
diff --git a/ledger-report.el b/ledger-report.el
index 6958a26..cb6237e 100644
--- a/ledger-report.el
+++ b/ledger-report.el
@@ -131,8 +131,7 @@ Calls `shrink-window-if-larger-than-buffer'."
   :group 'ledger-report)
 
 (defcustom ledger-report-use-strict nil
-  "Should Ledger-mode pass --strict as a command line parameter
-when running reports?"
+  "When non-nil, `ledger-mode' will use --strict when running reports?"
   :type 'boolean
   :package-version '(ledger-mode . "4.0.0")
   :group 'ledger-report)
@@ -476,7 +475,7 @@ Optionally EDIT the command."
   'action (lambda (_button) (ledger-report-visit-source)))
 
 (defun ledger-report--change-month (shift)
-  "Rebuild report with transactions from current month + shift."
+  "Rebuild report with transactions from current month + SHIFT."
   (let* ((current-month (or ledger-report-current-month (ledger-report--current-month)))
          (previous-month (ledger-report--shift-month current-month shift)))
     (set (make-local-variable 'ledger-report-current-month) previous-month)
diff --git a/ledger-schedule.el b/ledger-schedule.el
index 3a3e0ef..786df0c 100644
--- a/ledger-schedule.el
+++ b/ledger-schedule.el
@@ -68,9 +68,9 @@
                                        ("Fr" 5)
                                        ("Sa" 6)
                                        ("Su" 0))
-  "List of weekday abbreviations.  There must be exactly seven
-entries each with a two character abbreviation for a day and the
-number of that day in the week. "
+  "List of weekday abbreviations.
+There must be exactly seven entries each with a two character
+abbreviation for a day and the number of that day in the week."
   :type '(alist :value-type (group integer))
   :group 'ledger-schedule)
 
@@ -212,7 +212,7 @@ the transaction should be logged for that day."
 (defun ledger-schedule-constrain-year (year-desc month-desc day-desc)
   "Return a form that constrains the year.
 
-YEAR-DESC, MONT-DESC, and DAY-DESC are the string portions of the
+YEAR-DESC, MONTH-DESC, and DAY-DESC are the string portions of the
 date descriptor."
   (cond
    ((string-match "[A-Za-z]" day-desc) t) ; there is an advanced day descriptor which overrides the year
@@ -225,7 +225,7 @@ date descriptor."
 (defun ledger-schedule-constrain-month (year-desc month-desc day-desc)
   "Return a form that constrains the month.
 
-YEAR-DESC, MONT-DESC, and DAY-DESC are the string portions of the
+YEAR-DESC, MONTH-DESC, and DAY-DESC are the string portions of the
 date descriptor."
   (cond
    ((string-match "[A-Za-z]" day-desc) t) ; there is an advanced day descriptor which overrides the month
@@ -243,7 +243,7 @@ date descriptor."
 (defun ledger-schedule-constrain-day (year-desc month-desc day-desc)
   "Return a form that constrains the day.
 
-YEAR-DESC, MONT-DESC, and DAY-DESC are the string portions of the
+YEAR-DESC, MONTH-DESC, and DAY-DESC are the string portions of the
 date descriptor."
   (cond ((string= day-desc "*")
          t)
diff --git a/ledger-texi.el b/ledger-texi.el
index 7661d91..45eb281 100644
--- a/ledger-texi.el
+++ b/ledger-texi.el
@@ -18,6 +18,10 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
 ;; MA 02110-1301 USA.
+
+;;; Commentary:
+;;
+
 ;;; Code:
 (defvar ledger-binary-path)
 
@@ -26,12 +30,12 @@
   :group 'ledger)
 
 (defcustom ledger-texi-sample-doc-path "~/ledger/doc/sample.dat"
-  "Location for sample data to be used in texi tests"
+  "Location for sample data to be used in texi tests."
   :type 'file
   :group 'ledger-texi)
 
 (defcustom ledger-texi-normalization-args "--args-only --columns 80"
-  "texi normalization for producing ledger output"
+  "Texi normalization for producing ledger output."
   :type 'string
   :group 'ledger-texi)
 
@@ -171,3 +175,5 @@
                                 "../test/manual")))))
 
 (provide 'ledger-texi)
+
+;;; ledger-texi.el ends here