File: checkdoc.el.html

The Emacs Lisp manual has a nice chapter on how to write documentation strings. Many stylistic suggestions are fairly deterministic and easy to check for syntactically, but also easy to forget. The main checkdoc engine will perform the stylistic checks needed to make sure these styles are remembered.

There are four ways to use checkdoc:

  1) Use flymake-mode(var)/flymake-mode(fun). Type M-x flymake-mode in any Emacs Lisp
     buffer; the checkdoc back-end is enabled by default.

  2) Periodically use checkdoc or checkdoc-current-buffer.
     The checkdoc command is a more interactive version of
     checkdoc-current-buffer.

  3) Use checkdoc-minor-mode(var)/checkdoc-minor-mode(fun) to automatically check your
     documentation whenever you evaluate Lisp code with C-M-x
     or [menu-bar emacs-lisp eval-buffer]. Additional key-bindings
     are also provided under C-c ? KEY
       (add-hook 'emacs-lisp-mode-hook 'checkdoc-minor-mode)

  4) Use checkdoc-ispell to spellcheck docstrings interactively.

Using checkdoc:

  Most users will probably use checkdoc through flymake. The
commands checkdoc and checkdoc-ispell are the top-level entry points to all of the different checks that are available. It breaks examination of your Lisp file into four sections (comments, documentation, messages, and spacing) and indicates its current state in a status buffer.

  The Comments check examines your headers, footers, and
various tags (such as "Code:") to make sure that your code is ready for easy integration into existing systems.

  The Documentation check deals with documentation strings
and their elements that help make Emacs easier to use.

  The Messages check ensures that the strings displayed in the
minibuffer by some commands (such as error and y-or-n-p) are consistent with the Emacs environment.

  The Spacing check cleans up white-space at the end of lines.

  The interface while working with documentation and messages is
slightly different when being run in the interactive mode. The interface offers several options, including the ability to skip to the next error, or back up to previous errors. Auto-fixing is turned off at this stage, but you can use the f or F key to fix a given error (if the fix is available).

Auto-fixing:

  There are four classifications of style errors in terms of how
easy they are to fix. They are simple, complex, really complex, and impossible. (Impossible really means that checkdoc does not
have a fixing routine yet.) Typically white-space errors are
classified as simple, and are auto-fixed by default. Typographic changes are considered complex, and the user is asked if they want the problem fixed before checkdoc makes the change. These changes can be done without asking if checkdoc-autofix-flag is properly set. Potentially redundant changes are considered really complex, and the user is always asked before a change is inserted. The variable checkdoc-autofix-flag controls how these types of errors are fixed.

Spell checking text:

  The variable checkdoc-spellcheck-documentation-flag can be set
to customize how spell checking is to be done. Since spell checking can be quite slow, you can optimize how best you want your checking done. The default is defun, which spell checks each time checkdoc-defun or checkdoc-eval-defun is used. Setting to nil prevents spell checking during normal usage.
  Setting this variable to nil does not mean you cannot take
advantage of the spell checking. You can instead use the interactive functions checkdoc-ispell-* to check the spelling of your documentation.
  There is a list of Lisp-specific words which checkdoc will
install into Ispell on the fly, but only if Ispell is not already running. Use ispell-kill-ispell to make checkdoc restart it with these words enabled.
  See also the flyspell-prog-mode minor mode.

Checking parameters:

  You might not always want a function to have its parameters listed
in order. When this is the case, put the following comment just in
front of the documentation string: "; checkdoc-order: nil" This
overrides the value of checkdoc-arguments-in-order-flag.

  If you specifically wish to avoid mentioning a parameter of a
function in the doc string (such as a hidden parameter, or a parameter which is very obvious like events), you can have checkdoc skip looking for it by putting the following comment just in front of the documentation string: "; checkdoc-params: (args go here)"

Checking message strings:

  The text that follows the error and y-or-n-p commands is
also checked. The documentation for error clearly states some simple style rules to follow which checkdoc will auto-fix for you. y-or-n-p and yes-or-no-p should also end in "?".

Adding your own checks:

  You can experiment with adding your own checks by setting the
hooks checkdoc-style-functions and checkdoc-comment-style-functions. Return a string which is the error you wish to report. The cursor position should be preserved.

Error errors:

  Checkdoc does not always flag errors correctly. There are a
couple ways you can coax your file into passing all of checkdoc's tests through buffer local variables.

  The variable checkdoc-verb-check-experimental-flag can be used
to turn off the check for verb-voice in case you use words that are not semantically verbs, but are still in the incomplete list.

  The variable checkdoc-symbol-words can be a list of words that
happen to also be symbols. This is not a problem for one-word symbols, but if you use a hyphenated word that is also a symbol, then you may need this.

  The symbol checkdoc-force-docstrings-flag can be set to nil if
you have many undocumented functions you don't wish to document.

  See the above section "Checking Parameters" for details about
parameter checking.

Defined variables (42)

Defined functions (78)

Defined faces (0)