From a114a537452b56f1a59ce56c58ce4b106da8a924 Mon Sep 17 00:00:00 2001 From: Alex Branham Date: Sun, 6 Oct 2019 09:47:37 -0400 Subject: Documentation improvements Reported by checkdoc --- ledger-check.el | 7 ++++++- ledger-commodities.el | 9 +++++++-- ledger-context.el | 2 +- ledger-fonts.el | 2 +- ledger-mode.el | 8 +++----- ledger-reconcile.el | 17 +++++++++-------- ledger-regex.el | 8 ++++++++ ledger-report.el | 5 ++--- ledger-schedule.el | 12 ++++++------ ledger-texi.el | 10 ++++++++-- 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 -- cgit v1.2.3