comparison lisp/emacs-lisp/checkdoc.el @ 22195:bab34c7c16fb

Many doc fixes. Put two spaces between sentences. (checkdoc-this-string-valid-engine): Fix message. (checkdoc-ispell-lisp-words): Add "emacs".

22194:376bd8ec20f1

;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.

;;; Commentary:
;;
;;   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 two ways to use checkdoc:
;;   1) Periodically use `checkdoc'. `checkdoc-current-buffer' and
;;      `checkdoc-defun' to check your documentation.
;;   2) Use `checkdoc-minor-mode' 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
;;        (require 'checkdoc)
;;        (add-hook 'emacs-lisp-mode-hook
;;	             '(lambda () (checkdoc-minor-mode 1)))

;; 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 doc-strings:
;;
;;   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

;; 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.
;;
;; Checking parameters
;;

;;   You can experiment with adding your own checks by setting the
;; hooks `checkdoc-style-hooks' and `checkdoc-comment-style-hooks'.
;; Return a string which is the error you wish to report.  The cursor
;; position should be preserved.
;;
;; This file requires lisp-mnt (lisp maintenance routines) for the
;; comment checkers.
;;
;; Requires custom for emacs v20.

;;; Change log:
;; 0.1   Initial revision
;; 0.2   Fixed comments in this file to match the emacs lisp standards.
;;       Added new doc checks for: variable-flags, function arguments
;;       Added autofix functionality for white-space, and quoted variables.
;;       Unquoted symbols are allowed after ( character. (Sample code)
;;       Check for use of `? ' at end of line and warn.
;;       Check for spaces at end of lines for whole file, or one defun.
;;       Check for comments standards, including headinds like Code:
;;         and use of triple semicolons versus double semicolons
;;       Check that interactive functions have a doc-string.  Optionally
;;         set `checkdoc-force-docstrings-flag' to non-nil to make all
;;         definitions have a doc-string.
;; 0.3   Regexp changse for accuracy on var checking and param checking.
;;       lm-verify check expanded to each sub-call w/ more descriptive
;;         messages, and two autofix-options.
;;       Suggestions/patches from Christoph Wedler <[e-mail]>
;;         XEmacs support w/ extents/overlays.
;;         Better Whitespace finding regexps
;;         Added `checkdoc-arguments-in-order-flag' to optionally turn off
;;           warnings of arguments that do not appear in order in doc
;;           strings.
;; 0.4   New fix routine when two lines can be joined to make the
;;         first line a comlete sentence.
;;       Added ispell code.  Use `checkdoc-spellcheck-documentation-flag'
;;         to enable or disable this test in certain contexts.
;;       Added ispell interface functions `checkdoc-ispell',
;;         `checkdoc-ispell-continue', `checkdoc-ispell-defun'
;;         `checkdoc-ispell-interactive', `checkdoc-ispell-current-buffer'.
;;       Loop through all potential unquoted symbols.
;;       Auto-fixing no longer screws up the "end" of the doc-string.
;;       Maintain a different syntax table when examining arguments.
;;       Autofix enabled for parameters which are not uppercase iff they
;;         occur in lower case in the doc-string.
;;       Autofix enable if there is no Code: label.
;;       The comment text ";; checkdoc-order: nil|t" inside a defun to
;;         enable or disable the checking of argument order for one defun.
;;       The comment text ";; checkdoc-params: (arg1 arg2)" inside a defun
;;         (Such as just before the doc string) will list ARG1 and ARG2 as
;;         being paramters that need not show up in the doc string.
;;       Brought in suggestions from Jari Aalto <[e-mail]>
;;         More robustness (comments in/around doc-strings/ arg lists)
;;         Don't offer to `quote'afy symbols or keystroke representations
;;           that are in lists (sample code) This added new fn
;;           `checkdoc-in-sample-code-p'
;;         Added more comments near the ;;; comment check about why it
;;           is being done.  ;;; Are also now allowed inside a defun.
;;           This added the function `checkdoc-outside-major-sexp'
;;         Added `checkdoc-interactive' which permits interactive
;;           perusal of document warnings, and editing of strings.
;;         Fixed `checkdoc-defun-info' to be more robust when creating
;;           the paramter list.
;;         Added list of verbs in the wrong tense, and their fixes.
;;         Added defconst/subst/advice to checked items.
;;         Added `checkdoc-style-hooks' and `checkdoc-comment-style-hooks'
;;           for adding in user tests.
;;         Added `checkdoc-continue', a version of checkdoc that continues
;;           from point.
;;         [X]Emacs 20 support for extended characters.
;;         Only check comments on real files.
;;         Put `checkdoc' and `checkdoc-continue' into keymap/menu
;; 0.4.1 Made `custom' friendly.
;;       C-m in warning buffer also goes to error.
;;       Shrink error buffer to size of text.
;;       Added `checkdoc-tripple-semi-comment-check-flag'.
;;       `checkdoc-spellcheck-documentation-flag' off by default.
;;       Re-sorted check order so white space is removed before adding a .
;; 0.4.2 Added some more comments in the commentary.
;;       You can now `quote' symbols that look like keystrokes
;;       When spell checking, meta variables can end in `th' or `s'.
;; 0.4.3 Fixed bug where multi-function checking skips defuns that
;;         have comments before the doc-string.
;;       Fixed bug where keystrokes were identified from a variable name
;;         like ASSOC-P.
;; 0.5   Added checks for basics in messages using `error'.
;;       Added check for symbols that are both functions and symbols.
;;         These references are ambiguous and should be prefixed with
;;         "function", or "variable".  Added auto-fix for this also.
;;       Added auto fix for args that do not occur in the doc string.
;; 0.5.1 Fixed question about putting a symbol in `quotes'.
;;       Added spaces to the end of all y/n questions.
;;       Added checks for y/n question endings to require "? "

;;; TO DO:
;;   Hook into the byte compiler on a defun/defver level to generate
;;     warnings in the byte-compiler's warning/error buffer.
;;   Better ways to override more typical `eval' functions.  Advice

      nil)
    (defmacro defcustom (var value doc &rest args)
      (` (defvar (, var) (, value) (, doc))))))

(defcustom checkdoc-autofix-flag 'semiautomatic
  "*Non-nil means attempt auto-fixing of doc-strings.
If this value is the symbol 'query, then the user is queried before
any change is made. If the value is 'automatic, then all changes are
made without asking unless the change is very-complex.  If the value
is 'semiautomatic, or any other value, then simple fixes are made
without asking, and complex changes are made by asking the user first.
The value 'never is the same as nil, never ask or change anything."
  :group 'checkdoc
  :type '(choice (const automatic)
		 (const semiautomatic)
		 (const query)
		 (const never)))

(defcustom checkdoc-bouncy-flag t
  "*Non-nil means to 'bounce' to auto-fix locations.
Setting this to nil will silently make fixes that require no user
interaction.  See `checkdoc-autofix-flag' for auto-fixing details."
  :group 'checkdoc
  :type 'boolean)

(defcustom checkdoc-force-docstrings-flag t
  "*Non-nil means that all checkable definitions should have documentation.
Style guide dictates that interactive functions MUST have documentation,
and that its good but not required practice to make non user visible items
have doc-strings."
  :group 'checkdoc
  :type 'boolean)

(defcustom checkdoc-tripple-semi-comment-check-flag t
  "*Non-nil means to check for multiple adjacent occurrences of ;;; comments.
According to the style of emacs code in the lisp libraries, a block
comment can look like this:
;;; Title
;;  text
;;  text
But when inside a function, code can be commented out using the ;;;

is ignored regardless of it's location in the code."
  :group 'checkdoc
  :type 'boolean)

(defcustom checkdoc-spellcheck-documentation-flag nil
  "*Non-nil means run ispell on doc-strings based on value.
This will be automatically set to nil if ispell does not exist on your
system.  Possible values are:

  nil          - Don't spell-check during basic style checks.
  'defun       - Spell-check when style checking a single defun
  'buffer      - Spell-check only when style checking the whole buffer
  'interactive - Spell-check only during `checkdoc-interactive'
  t            - Always spell-check"
  :group 'checkdoc
  :type '(choice (const nil)
		 (const defun)
		 (const buffer)
		 (const interactive)
		 (const t)))

(defvar checkdoc-ispell-lisp-words
  '("alist" "etags" "iff" "keymap" "paren" "regexp" "sexp" "xemacs")
  "List of words that are correct when spell-checking lisp documentation.")

(defcustom checkdoc-max-keyref-before-warn 10
  "*The number of \\ [command-to-keystroke] tokens allowed in a doc-string.
Any more than this and a warning is generated suggesting that the construct
\\ {keymap} be used instead."
  :group 'checkdoc
  :type 'integer)

\\s-+\\(\\(\\sw\\|\\s_\\)+\\)[ \t\n]+"
  "Regular expression used to identify a defun.
A search leaves the cursor in front of the parameter list.")

(defcustom checkdoc-verb-check-experimental-flag t
  "*Non-nil means to attempt to check the voice of the doc-string.
This check keys off some words which are commonly misused.  See the
variable `checkdoc-common-verbs-wrong-voice' if you wish to add your
own."
  :group 'checkdoc
  :type 'boolean)

(defvar checkdoc-common-verbs-regexp nil
  "Regular expression derived from `checkdoc-common-verbs-regexp'.")

  "Syntax table used by checkdoc in document strings.")

(if checkdoc-syntax-table
    nil
  (setq checkdoc-syntax-table (copy-syntax-table emacs-lisp-mode-syntax-table))
  ;; When dealing with syntax in doc-strings, make sure that - are encompased
  ;; in words so we can use cheap \\> to get the end of a symbol, not the
  ;; end of a word in a conglomerate.
  (modify-syntax-entry ?- "w" checkdoc-syntax-table)
  )
	

    "Add to the value of LIST-VAR the element ELEMENT if it isn't there yet."
    (if (not (member element (symbol-value list-var)))
	(set list-var (cons element (symbol-value list-var)))))
  )

;; To be safe in new emacsen, we want to read events, not characters
(if (fboundp 'read-event)
    (defalias 'checkdoc-read-event 'read-event)
  (defalias 'checkdoc-read-event 'read-char))

;;; User level commands
;;
;;;###autoload
(defun checkdoc-eval-current-buffer ()
  "Evaluate and check documentation for the current buffer.
Evaluation is done first because good documentation for something that
doesn't work is just not useful.  Comments, doc-strings, and rogue
spacing are all verified."
  (interactive)
  (checkdoc-call-eval-buffer nil)
  (checkdoc-current-buffer t))

;;;###autoload
(defun checkdoc-current-buffer (&optional take-notes)
  "Check current buffer for document, comment, error style, and rogue spaces.
Optional argument TAKE-NOTES non-nil will store all found errors in a
warnings buffer, otherwise it stops after the first error."
  (interactive "P")
  (if (interactive-p) (message "Checking buffer for style..."))
  ;; Assign a flag to spellcheck flag
  (let ((checkdoc-spellcheck-documentation-flag
	 (memq checkdoc-spellcheck-documentation-flag '(buffer t))))

    (if (not (car err-list)) (setq err-list nil))
    ;; Include whatever function point is in for good measure.
    (beginning-of-defun)
    (while err-list
      (goto-char (cdr (car err-list)))
      ;; The cursor should be just in front of the offending doc-string
      (let ((cdo (save-excursion
		   (checkdoc-make-overlay (point)
					  (progn (forward-sexp 1)
						 (point)))))
	    c)
	(unwind-protect
	    (progn
	      (checkdoc-overlay-put cdo 'face 'highlight)
	      ;; Make sure the whole doc-string is visible if possible.
	      (sit-for 0)
	      (if (not (pos-visible-in-window-p
			(save-excursion (forward-sexp 1) (point))
			(selected-window)))
		  (recenter))

error was found.  We can use points and not markers because we promise
not to edit the buffer before point without re-executing this check."
  (let ((msg nil) (p (point)))
    (condition-case nil
	(while (and (not msg) (checkdoc-next-docstring))
	  (message "Searching for doc-string error...%d%%"
		   (/ (* 100 (point)) (point-max)))
	  (if (setq msg (checkdoc-this-string-valid))
	      (setq msg (cons msg (point)))))
      ;; Quit.. restore position,  Other errors, leave alone
      (quit (goto-char p)))

    (goto-char p)
    nil))

;;;###autoload
(defun checkdoc-continue (&optional take-notes)
  "Find the next doc-string in the current buffer which is stylisticly poor.
Prefix argument TAKE-NOTES means to continue through the whole buffer and
save warnings in a separate buffer.  Second optional argument START-POINT
is the starting location.  If this is nil, `point-min' is used instead."
  (interactive "P")
  (let ((wrong nil) (msg nil) (errors nil)

    (save-excursion
      ;; If we are taking notes, encompass the whole buffer, otherwise
      ;; the user is navigating down through the buffer.
      (if take-notes (checkdoc-start-section "checkdoc"))
      (while (and (not wrong) (checkdoc-next-docstring))
	;; OK, lets look at the doc-string.
	(setq msg (checkdoc-this-string-valid))
	(if msg
	    ;; Oops
	    (if take-notes
		(progn

	(checkdoc-show-diagnostics)
      (if (interactive-p)
	  (message "No style warnings.")))))

(defun checkdoc-next-docstring ()
  "Find the next doc-string after point and return t.
Return nil if there are no more doc-strings."
  (if (not (re-search-forward checkdoc-defun-regexp nil t))
      nil
    ;; search drops us after the identifier.  The next sexp is either
    ;; the argument list or the value of the variable.  skip it.
    (forward-sexp 1)
    (skip-chars-forward " \n\t")
    t))

;;; ###autoload
(defun checkdoc-comments (&optional take-notes)
  "Find missing comment sections in the current emacs lisp file.
Prefix argument TAKE-NOTES non-nil means to save warnings in a
separate buffer.  Otherwise print a message.  This returns the error
if there is one."
  (interactive "P")
  (if take-notes (checkdoc-start-section "checkdoc-comments"))

  (eval-defun nil)
  (checkdoc-defun))

;;;###autoload
(defun checkdoc-defun (&optional no-error)
  "Examine the doc-string of the function or variable under point.
Calls `error' if the doc-string produces diagnostics.  If NO-ERROR is
non-nil, then do not call error, but call `message' instead.
If the document check passes, then check the function for rogue white
space at the end of each line."
  (interactive)
  (save-excursion
    (beginning-of-defun)
    (if (not (looking-at checkdoc-defun-regexp))
	;; I found this more annoying than useful.
	;;(if (not no-error)
	;;    (message "Cannot check this sexp's doc-string."))
	nil
      ;; search drops us after the identifier.  The next sexp is either
      ;; the argument list or the value of the variable.  skip it.
      (goto-char (match-end 0))
      (forward-sexp 1)

  (let ((checkdoc-spellcheck-documentation-flag t))
    (call-interactively 'checkdoc-comments nil current-prefix-arg)))

;;;###autoload
(defun checkdoc-ispell-defun (&optional take-notes)
  "Check the style and spelling of the current defun with ispell.
Calls `checkdoc-defun' with spell-checking turned on.
Prefix argument TAKE-NOTES is the same as for `checkdoc-defun'"
  (interactive)
  (let ((checkdoc-spellcheck-documentation-flag t))
    (call-interactively 'checkdoc-defun nil current-prefix-arg)))

    (checkdoc-add-to-list 'minor-mode-map-alist (cons 'checkdoc-minor-mode
						      checkdoc-minor-keymap))))

;;;###autoload
(defun checkdoc-minor-mode (&optional arg)
  "Toggle checkdoc minor mode.  A mode for checking lisp doc-strings.
With prefix ARG, turn checkdoc minor mode on iff ARG is positive.

In checkdoc minor mode, the usual bindings for `eval-defun' which is
bound to \\<checkdoc-minor-keymap> \\[checkdoc-eval-defun] and `checkdoc-eval-current-buffer' are overridden to include
checking of documentation strings.

\\{checkdoc-minor-keymap}"
  (interactive "P")

(defsubst checkdoc-run-hooks (hookvar &rest args)
  "Run hooks in HOOKVAR with ARGS."
  (if (fboundp 'run-hook-with-args-until-success)
      (apply 'run-hook-with-args-until-success hookvar args)
    ;; This method was similar to above.  We ignore the warning
    ;; since we will use the above for future emacs versions
    (apply 'run-hook-with-args hookvar args)))

(defsubst checkdoc-create-common-verbs-regexp ()
  "Rebuild the contents of `checkdoc-common-verbs-regexp'."
  (or checkdoc-common-verbs-regexp

;;    found))

;;; Checking engines
;;
(defun checkdoc-this-string-valid ()
  "Return a message string if the current doc-string is invalid.
Check for style only, such as the first line always being a complete
sentence, whitespace restrictions, and making sure there are no
hard-coded key-codes such as C-[char] or mouse-[number] in the comment.
See the style guide in the Emacs Lisp manual for more details."

  ;; Jump over comments between the last object and the doc-string
  (while (looking-at "[ \t\n]*;")
    (forward-line 1)
    (beginning-of-line)
    (skip-chars-forward " \n\t"))

	    (set-syntax-table checkdoc-syntax-table)
	    (checkdoc-this-string-valid-engine))
	(set-syntax-table old-syntax-table)))))

(defun checkdoc-this-string-valid-engine ()
  "Return a message string if the current doc-string is invalid.
Depends on `checkdoc-this-string-valid' to reset the syntax table so that
regexp short cuts work."
  (let ((case-fold-search nil)
	;; Use a marker so if an early check modifies the text,
	;; we won't accidentally loose our place.  This could cause
	;; end-of doc-string whitespace to also delete the " char.
	(e (save-excursion (forward-sexp 1) (point-marker)))
	(fp (checkdoc-defun-info)))
    (or
     ;; * *Do not* indent subsequent lines of a documentation string so that
     ;;   the text is lined up in the source code with the text of the first

     ;;   save space by using a comment instead of a documentation string,
     ;;   but that is no longer the case.
     (if (and (not (nth 1 fp))		; not a variable
	      (or (nth 2 fp)		; is interactive
		  checkdoc-force-docstrings-flag) ;or we always complain
	      (not (checkdoc-char= (following-char) ?\"))) ; no doc-string
	 (if (nth 2 fp)
	     "All interactive functions should have documentation"
	   "All variables and subroutines might as well have a \
documentation string"))
     ;; * The first line of the documentation string should consist of one

			   l2 (save-excursion
				(forward-line 1)
				(end-of-line)
				(current-column)))
		     (if (> (+ l1 l2 1) 80)
			 (setq msg "Incomplete auto-fix.  Doc-string \
may require more formatting")
		       ;; We can merge these lines!  Replace this CR
		       ;; with a space.
		       (delete-char 1) (insert " ")
		       (setq msg nil))))

							      (point))
					   t)
			(< (current-column) numc))
		   (if (checkdoc-autofix-ask-replace
			p (1+ p)
			"1st line not a complete sentence. Join these lines? "
			" " t)
		       (progn
			 ;; They said yes.  We have more fill work to do...
			 (delete-char 1)
			 (insert "\n")

	 (while (and (not f) (setq m (re-search-forward re e t)))
	   (setq f (not (checkdoc-in-sample-code-p start e))))
	 (if m
	     (concat
	      "Keycode " (match-string 1)
	      " embedded in doc-string.  Use \\\\<keymap> & \\\\[function] "
	      "instead"))))
     ;; It is not practical to use `\\[...]' very many times, because
     ;; display of the documentation string will become slow.  So use this
     ;; to describe the most important commands in your major mode, and
     ;; then use `\\{...}' to display the rest of the mode's keymap.
     (save-excursion
       (if (re-search-forward "\\\\\\\\\\[\\w+" e t
			      (1+ checkdoc-max-keyref-before-warn))
	   "Too many occurrences of \\[function].  Use \\{keymap} instead"))
     ;; Ambiguous quoted symbol. When a symbol is both bound and fbound,
     ;; and is referred to in documentation, it should be prefixed with
     ;; something to disambiguate it.  This check must be before the
     ;; 80 column check because it will probably break that.
     (save-excursion
       (let ((case-fold-search t)

		 (setq ms (substring ms 0 (1- (length ms))))))
	   (if (and (not (checkdoc-in-sample-code-p start e))
		    (setq found (intern-soft ms))
		    (or (boundp found) (fboundp found)))
	       (progn
		 (setq msg (format "Add quotes around lisp symbol `%s'? "
				   ms))
		 (if (checkdoc-autofix-ask-replace
		      (match-beginning 1) (+ (match-beginning 1)
					     (length ms))
		      msg (concat "`" ms "'") t)

     ;; t and nil case
     (save-excursion
       (if (re-search-forward "\\(`\\(t\\|nil\\)'\\)" e t)
	   (if (checkdoc-autofix-ask-replace
		(match-beginning 1) (match-end 1)
		(format "%s should not appear in quotes. Remove? "
			(match-string 2))
		(match-string 2) t)
	       nil
	     "Symbols t and nil should not appear in `quotes'")))
     ;; Here we deviate to tests based on a variable or function.

	     ;;   condition, give it a name that ends in `-flag'.

	     ;; If the variable has -flag in the name, make sure
	     (if (and (string-match "-flag$" (car fp))
		      (not (looking-at "\"\\*?Non-nil\\s-+means\\s-+")))
		 "Flag variable doc-strings should start: Non-nil means")
	     ;; If the doc-string starts with "Non-nil means"
	     (if (and (looking-at "\"\\*?Non-nil\\s-+means\\s-+")
		      (not (string-match "-flag$" (car fp))))
		 "Flag variables should end in: -flag")
	     ;; Done with variables
	     ))
	   (t
	    ;; This if we are in a function definition
	    (or

					  "\\)\\(\\>\\|th\\>\\|s\\>\\)")
				  e t))
			     (if (checkdoc-autofix-ask-replace
				  (match-beginning 1) (match-end 1)
				  (format
				   "Argument `%s' should appear as `%s'. Fix? "
				   (car args) (upcase (car args)))
				  (upcase (car args)) t)
				 (setq found (match-beginning 1))))))
		   (if found (setq args (cdr args)))))
	       (if (not found)
		   ;; It wasn't found at all!  Offer to attach this new symbol
		   ;; to the end of the documentation string.
		   (if (y-or-n-p
			(format "Add %s documentation to end of doc-string?"
				(upcase (car args))))
		       ;; No do some majic an invent a doc string.
		       (save-excursion
			 (goto-char e) (forward-char -1)
			 (insert "\n"
				 (if inopts "Optional a" "A")
				 "rgument " (upcase (car args))

			 (if (not (save-excursion (forward-char -1)
						  (looking-at "[.?!]")))
			     (insert "."))
			 nil)
		     (format
		      "Argument `%s' should appear as `%s' in the doc-string"
		      (car args) (upcase (car args))))
		 (if (or (and order (eq order 'yes))
			 (and (not order) checkdoc-arguments-in-order-flag))
		     (if (< found last-pos)
			 "Arguments occur in the doc-string out of order"))))
	     ;; Done with functions
	     )))
     ;; Make sure the doc-string has correctly spelled english words
     ;; in it.  This functions is extracted due to it's complexity,
     ;; and reliance on the ispell program.
     (checkdoc-ispell-docstring-engine e)
     ;; User supplied checks
     (save-excursion (checkdoc-run-hooks 'checkdoc-style-hooks fp e))
     ;; Done!
     )))

(defun checkdoc-defun-info nil
  "Return a list of details about the current sexp.
It is a list of the form:
   '( NAME VARIABLE INTERACTIVE NODOCPARAMS PARAMETERS ... )
where NAME is the name, VARIABLE is t if this is a `defvar',
INTERACTIVE is nil if this is not an interactive function, otherwise
it is the position of the `interactive' call, and PARAMETERS is a
string which is the name of each variable in the function's argument
list.  The NODOCPARAMS is a sublist of parameters specified by a checkdoc

	    (setq ret (cons (symbol-name (car lst)) ret)
		  lst (cdr lst)))))
      (nreverse ret))))

(defun checkdoc-in-sample-code-p (start limit)
  "Return Non-nil if the current point is in a code-fragment.
A code fragment is identified by an open parenthesis followed by a
symbol which is a valid function, or a parenthesis that is quoted with the '
character.  Only the region from START to LIMIT is is allowed while
searching for the bounding parenthesis."
  (save-match-data

;;; Ispell engine
;;
(eval-when-compile (require 'ispell))

(defun checkdoc-ispell-init ()
  "Initialize ispell process (default version) with lisp words.
The words used are from `checkdoc-ispell-lisp-words'.  If `ispell'
cannot be loaded, then set `checkdoc-spellcheck-documentation-flag' to
nil."
  (require 'ispell)
  (if (not (symbol-value 'ispell-process)) ;Silence byteCompiler
      (condition-case nil
	  (progn
	    (ispell-buffer-local-words)
	    ;; This code copied in part from ispell.el emacs 19.34
	    (let ((w checkdoc-ispell-lisp-words))
	      (while w
		(process-send-string
		 ;;  Silence byte compiler
		 (symbol-value 'ispell-process)
		 (concat "@" (car w) "\n"))
		(setq w (cdr w)))))
	(error (setq checkdoc-spellcheck-documentation-flag nil)))))

(defun checkdoc-ispell-docstring-engine (end)
  "Run the ispell tools on the doc-string between point and END.
Since ispell isn't lisp smart, we must pre-process the doc-string
before using the ispell engine on it."
  (if (not checkdoc-spellcheck-documentation-flag)
      nil
    (checkdoc-ispell-init)
    (save-excursion
      (skip-chars-forward "^a-zA-Z")

Some editors & news agents may remove it")))
     ;; Check for, and pottentially remove whitespace appearing at the
     ;; end of different lines.
     (progn
       (goto-char start)
       ;; There is no documentation in the elisp manual about this check,
       ;; it is intended to help clean up messy code and reduce the file size.
       (while (and (not msg) (re-search-forward "[^ \t\n]\\([ \t]+\\)$" end t))
	 ;; This is not a complex activity
	 (if (checkdoc-autofix-ask-replace
	      (match-beginning 1) (match-end 1)
	      "White space at end of line. Remove? " "")
	     nil
	   (setq msg "White space found at end of line")))))
    ;; Return an error and leave the cursor at that spot, or restore
    ;; the cursor.
    (if msg

  ;; a) get symbols for comple and
  ;; b) determine if we have lm-history symbol which doesn't always exist
  (require 'lisp-mnt))

(defun checkdoc-file-comments-engine ()
  "Return a message string if this file does not match the emacs standard.
This checks for style only, such as the first line, Commentary:,
Code:, and others referenced in the style guide."
  (if (featurep 'lisp-mnt)
      nil
    (require 'lisp-mnt)

	   (let ((complex-replace t))
	     (while (looking-at ";;\\(;\\)[^;]")
	       (if (and (checkdoc-outside-major-sexp) ;in code is ok.
			(checkdoc-autofix-ask-replace
			 (match-beginning 1) (match-end 1)
			 "Multiple occurances of ;;; found. Use ;; instead? "
			 "" complex-replace))
		   ;; Learn that, yea, the user did want to do this a
		   ;; whole bunch of times.
		   (setq complex-replace nil))
	       (beginning-of-line)

       ;; visible section (with the finder)
       (save-excursion
	 (goto-char (lm-commentary-mark))
	 ;; Spellcheck between the commentary, and the first
	 ;; non-comment line.  We could use lm-commentary, but that
	 ;; returns a string, and ispell wants to talk to a buffer.
	 ;; Since the comments talk about lisp, use the specialized
	 ;; spell-checker we also used for doc-strings.
	 (checkdoc-ispell-docstring-engine (save-excursion
					     (re-search-forward "^[^;]" nil t)
					     (point))))
;;; test comment out code
;;;       (foo 1 3)

		 (beginning-of-line)))
    (other-window -1)
    (shrink-window-if-larger-than-buffer)))

(defgroup checkdoc nil
  "Support for doc-string checking in emacs lisp."
  :prefix "checkdoc"
  :group 'lisp
  :version "20.3")

(custom-add-option 'emacs-lisp-mode-hook
		   (lambda () (checkdoc-minor-mode 1)))

(provide 'checkdoc)
;;; checkdoc.el ends here

22195:bab34c7c16fb

;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.

;;; Commentary:
;;
;;   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 two ways to use checkdoc:
;;   1) Periodically use `checkdoc'. `checkdoc-current-buffer' and
;;      `checkdoc-defun' to check your documentation.
;;   2) Use `checkdoc-minor-mode' 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
;;        (require 'checkdoc)
;;        (add-hook 'emacs-lisp-mode-hook
;;	             '(lambda () (checkdoc-minor-mode 1)))

;; 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 doc strings:
;;
;;   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

;; 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.
;;
;; Checking parameters
;;

;;   You can experiment with adding your own checks by setting the
;; hooks `checkdoc-style-hooks' and `checkdoc-comment-style-hooks'.
;; Return a string which is the error you wish to report.  The cursor
;; position should be preserved.
;;
;; This file requires lisp-mnt (Lisp maintenance routines) for the
;; comment checkers.

;;; TO DO:
;;   Hook into the byte compiler on a defun/defver level to generate
;;     warnings in the byte-compiler's warning/error buffer.
;;   Better ways to override more typical `eval' functions.  Advice

      nil)
    (defmacro defcustom (var value doc &rest args)
      (` (defvar (, var) (, value) (, doc))))))

(defcustom checkdoc-autofix-flag 'semiautomatic
  "*Non-nil means attempt auto-fixing of doc strings.
If this value is the symbol `query', then the user is queried before
any change is made.  If the value is `automatic', then all changes are
made without asking unless the change is very-complex.  If the value
is `semiautomatic', or any other value, then simple fixes are made
without asking, and complex changes are made by asking the user first.
The value `never' is the same as nil, never ask or change anything."
  :group 'checkdoc
  :type '(choice (const automatic)
		 (const semiautomatic)
		 (const query)
		 (const never)))

(defcustom checkdoc-bouncy-flag t
  "*Non-nil means to \"bounce\" to auto-fix locations.
Setting this to nil will silently make fixes that require no user
interaction.  See `checkdoc-autofix-flag' for auto-fixing details."
  :group 'checkdoc
  :type 'boolean)

(defcustom checkdoc-force-docstrings-flag t
  "*Non-nil means that all checkable definitions should have documentation.
Style guide dictates that interactive functions MUST have documentation,
and that its good but not required practice to make non user visible items
have doc strings."
  :group 'checkdoc
  :type 'boolean)

(defcustom checkdoc-tripple-semi-comment-check-flag t
  "*Non-nil means to check for multiple adjacent occurrences of ;;; comments.
According to the style of Emacs code in the Lisp libraries, a block
comment can look like this:
;;; Title
;;  text
;;  text
But when inside a function, code can be commented out using the ;;;

is ignored regardless of it's location in the code."
  :group 'checkdoc
  :type 'boolean)

(defcustom checkdoc-spellcheck-documentation-flag nil
  "*Non-nil means run Ispell on doc strings based on value.
This is automatically set to nil if Ispell does not exist on your
system.  Possible values are:

  nil         - Don't spell-check during basic style checks.
  defun       - Spell-check when style checking a single defun
  buffer      - Spell-check only when style checking the whole buffer
  interactive - Spell-check only during `checkdoc-interactive'
  t           - Always spell-check"
  :group 'checkdoc
  :type '(choice (const nil)
		 (const defun)
		 (const buffer)
		 (const interactive)
		 (const t)))

(defvar checkdoc-ispell-lisp-words
  '("alist" "etags" "iff" "keymap" "paren" "regexp" "sexp" "emacs" "xemacs")
  "List of words that are correct when spell-checking Lisp documentation.")

(defcustom checkdoc-max-keyref-before-warn 10
  "*The number of \\ [command-to-keystroke] tokens allowed in a doc string.
Any more than this and a warning is generated suggesting that the construct
\\ {keymap} be used instead."
  :group 'checkdoc
  :type 'integer)

\\s-+\\(\\(\\sw\\|\\s_\\)+\\)[ \t\n]+"
  "Regular expression used to identify a defun.
A search leaves the cursor in front of the parameter list.")

(defcustom checkdoc-verb-check-experimental-flag t
  "*Non-nil means to attempt to check the voice of the doc string.
This check keys off some words which are commonly misused.  See the
variable `checkdoc-common-verbs-wrong-voice' if you wish to add your own."
  :group 'checkdoc
  :type 'boolean)

(defvar checkdoc-common-verbs-regexp nil
  "Regular expression derived from `checkdoc-common-verbs-regexp'.")

  "Syntax table used by checkdoc in document strings.")

(if checkdoc-syntax-table
    nil
  (setq checkdoc-syntax-table (copy-syntax-table emacs-lisp-mode-syntax-table))
  ;; When dealing with syntax in doc strings, make sure that - are encompased
  ;; in words so we can use cheap \\> to get the end of a symbol, not the
  ;; end of a word in a conglomerate.
  (modify-syntax-entry ?- "w" checkdoc-syntax-table)
  )
	

    "Add to the value of LIST-VAR the element ELEMENT if it isn't there yet."
    (if (not (member element (symbol-value list-var)))
	(set list-var (cons element (symbol-value list-var)))))
  )

;; To be safe in new Emacsen, we want to read events, not characters
(if (fboundp 'read-event)
    (defalias 'checkdoc-read-event 'read-event)
  (defalias 'checkdoc-read-event 'read-char))

;;; User level commands
;;
;;;###autoload
(defun checkdoc-eval-current-buffer ()
  "Evaluate and check documentation for the current buffer.
Evaluation is done first because good documentation for something that
doesn't work is just not useful.  Comments, doc strings, and rogue
spacing are all verified."
  (interactive)
  (checkdoc-call-eval-buffer nil)
  (checkdoc-current-buffer t))

;;;###autoload
(defun checkdoc-current-buffer (&optional take-notes)
  "Check current buffer for document, comment, error style, and rogue spaces.
With a prefix argument (in Lisp, the argument TAKE-NOTES),
store all errors found in a warnings buffer,
otherwise stop after the first error."
  (interactive "P")
  (if (interactive-p) (message "Checking buffer for style..."))
  ;; Assign a flag to spellcheck flag
  (let ((checkdoc-spellcheck-documentation-flag
	 (memq checkdoc-spellcheck-documentation-flag '(buffer t))))

    (if (not (car err-list)) (setq err-list nil))
    ;; Include whatever function point is in for good measure.
    (beginning-of-defun)
    (while err-list
      (goto-char (cdr (car err-list)))
      ;; The cursor should be just in front of the offending doc string
      (let ((cdo (save-excursion
		   (checkdoc-make-overlay (point)
					  (progn (forward-sexp 1)
						 (point)))))
	    c)
	(unwind-protect
	    (progn
	      (checkdoc-overlay-put cdo 'face 'highlight)
	      ;; Make sure the whole doc string is visible if possible.
	      (sit-for 0)
	      (if (not (pos-visible-in-window-p
			(save-excursion (forward-sexp 1) (point))
			(selected-window)))
		  (recenter))

error was found.  We can use points and not markers because we promise
not to edit the buffer before point without re-executing this check."
  (let ((msg nil) (p (point)))
    (condition-case nil
	(while (and (not msg) (checkdoc-next-docstring))
	  (message "Searching for doc string error...%d%%"
		   (/ (* 100 (point)) (point-max)))
	  (if (setq msg (checkdoc-this-string-valid))
	      (setq msg (cons msg (point)))))
      ;; Quit.. restore position,  Other errors, leave alone
      (quit (goto-char p)))

    (goto-char p)
    nil))

;;;###autoload
(defun checkdoc-continue (&optional take-notes)
  "Find the next docstring in the current buffer which is stylisticly poor.
Prefix argument TAKE-NOTES means to continue through the whole buffer and
save warnings in a separate buffer.  Second optional argument START-POINT
is the starting location.  If this is nil, `point-min' is used instead."
  (interactive "P")
  (let ((wrong nil) (msg nil) (errors nil)

    (save-excursion
      ;; If we are taking notes, encompass the whole buffer, otherwise
      ;; the user is navigating down through the buffer.
      (if take-notes (checkdoc-start-section "checkdoc"))
      (while (and (not wrong) (checkdoc-next-docstring))
	;; OK, lets look at the doc string.
	(setq msg (checkdoc-this-string-valid))
	(if msg
	    ;; Oops
	    (if take-notes
		(progn

	(checkdoc-show-diagnostics)
      (if (interactive-p)
	  (message "No style warnings.")))))

(defun checkdoc-next-docstring ()
  "Move to the next doc string after point, and return t.
Return nil if there are no more doc strings."
  (if (not (re-search-forward checkdoc-defun-regexp nil t))
      nil
    ;; search drops us after the identifier.  The next sexp is either
    ;; the argument list or the value of the variable.  skip it.
    (forward-sexp 1)
    (skip-chars-forward " \n\t")
    t))

;;; ###autoload
(defun checkdoc-comments (&optional take-notes)
  "Find missing comment sections in the current Emacs Lisp file.
Prefix argument TAKE-NOTES non-nil means to save warnings in a
separate buffer.  Otherwise print a message.  This returns the error
if there is one."
  (interactive "P")
  (if take-notes (checkdoc-start-section "checkdoc-comments"))

  (eval-defun nil)
  (checkdoc-defun))

;;;###autoload
(defun checkdoc-defun (&optional no-error)
  "Examine the doc string of the function or variable under point.
Call `error' if the doc string has problems.  If NO-ERROR is
non-nil, then do not call error, but call `message' instead.
If the doc string passes the test, then check the function for rogue white
space at the end of each line."
  (interactive)
  (save-excursion
    (beginning-of-defun)
    (if (not (looking-at checkdoc-defun-regexp))
	;; I found this more annoying than useful.
	;;(if (not no-error)
	;;    (message "Cannot check this sexp's docstring."))
	nil
      ;; search drops us after the identifier.  The next sexp is either
      ;; the argument list or the value of the variable.  skip it.
      (goto-char (match-end 0))
      (forward-sexp 1)

  (let ((checkdoc-spellcheck-documentation-flag t))
    (call-interactively 'checkdoc-comments nil current-prefix-arg)))

;;;###autoload
(defun checkdoc-ispell-defun (&optional take-notes)
  "Check the style and spelling of the current defun with Ispell.
Calls `checkdoc-defun' with spell-checking turned on.
Prefix argument TAKE-NOTES is the same as for `checkdoc-defun'"
  (interactive)
  (let ((checkdoc-spellcheck-documentation-flag t))
    (call-interactively 'checkdoc-defun nil current-prefix-arg)))

    (checkdoc-add-to-list 'minor-mode-map-alist (cons 'checkdoc-minor-mode
						      checkdoc-minor-keymap))))

;;;###autoload
(defun checkdoc-minor-mode (&optional arg)
  "Toggle Checkdoc minor mode, a mode for checking Lisp doc strings.
With prefix ARG, turn Checkdoc minor mode on iff ARG is positive.

In Checkdoc minor mode, the usual bindings for `eval-defun' which is
bound to \\<checkdoc-minor-keymap> \\[checkdoc-eval-defun] and `checkdoc-eval-current-buffer' are overridden to include
checking of documentation strings.

\\{checkdoc-minor-keymap}"
  (interactive "P")

(defsubst checkdoc-run-hooks (hookvar &rest args)
  "Run hooks in HOOKVAR with ARGS."
  (if (fboundp 'run-hook-with-args-until-success)
      (apply 'run-hook-with-args-until-success hookvar args)
    ;; This method was similar to above.  We ignore the warning
    ;; since we will use the above for future Emacs versions
    (apply 'run-hook-with-args hookvar args)))

(defsubst checkdoc-create-common-verbs-regexp ()
  "Rebuild the contents of `checkdoc-common-verbs-regexp'."
  (or checkdoc-common-verbs-regexp

;;    found))

;;; Checking engines
;;
(defun checkdoc-this-string-valid ()
  "Return a message string if the current doc string is invalid.
Check for style only, such as the first line always being a complete
sentence, whitespace restrictions, and making sure there are no
hard-coded key-codes such as C-[char] or mouse-[number] in the comment.
See the style guide in the Emacs Lisp manual for more details."

  ;; Jump over comments between the last object and the doc string
  (while (looking-at "[ \t\n]*;")
    (forward-line 1)
    (beginning-of-line)
    (skip-chars-forward " \n\t"))

	    (set-syntax-table checkdoc-syntax-table)
	    (checkdoc-this-string-valid-engine))
	(set-syntax-table old-syntax-table)))))

(defun checkdoc-this-string-valid-engine ()
  "Return a message string if the current doc string is invalid.
Depends on `checkdoc-this-string-valid' to reset the syntax table so that
regexp short cuts work."
  (let ((case-fold-search nil)
	;; Use a marker so if an early check modifies the text,
	;; we won't accidentally loose our place.  This could cause
	;; end-of doc string whitespace to also delete the " char.
	(e (save-excursion (forward-sexp 1) (point-marker)))
	(fp (checkdoc-defun-info)))
    (or
     ;; * *Do not* indent subsequent lines of a documentation string so that
     ;;   the text is lined up in the source code with the text of the first

     ;;   save space by using a comment instead of a documentation string,
     ;;   but that is no longer the case.
     (if (and (not (nth 1 fp))		; not a variable
	      (or (nth 2 fp)		; is interactive
		  checkdoc-force-docstrings-flag) ;or we always complain
	      (not (checkdoc-char= (following-char) ?\"))) ; no doc string
	 (if (nth 2 fp)
	     "All interactive functions should have documentation"
	   "All variables and subroutines might as well have a \
documentation string"))
     ;; * The first line of the documentation string should consist of one

			   l2 (save-excursion
				(forward-line 1)
				(end-of-line)
				(current-column)))
		     (if (> (+ l1 l2 1) 80)
			 (setq msg "Incomplete auto-fix; doc string \
may require more formatting")
		       ;; We can merge these lines!  Replace this CR
		       ;; with a space.
		       (delete-char 1) (insert " ")
		       (setq msg nil))))

							      (point))
					   t)
			(< (current-column) numc))
		   (if (checkdoc-autofix-ask-replace
			p (1+ p)
			"1st line not a complete sentence.  Join these lines? "
			" " t)
		       (progn
			 ;; They said yes.  We have more fill work to do...
			 (delete-char 1)
			 (insert "\n")

	 (while (and (not f) (setq m (re-search-forward re e t)))
	   (setq f (not (checkdoc-in-sample-code-p start e))))
	 (if m
	     (concat
	      "Keycode " (match-string 1)
	      " embedded in doc string.  Use \\\\<keymap> & \\\\[function] "
	      "instead"))))
     ;; It is not practical to use `\\[...]' very many times, because
     ;; display of the documentation string will become slow.  So use this
     ;; to describe the most important commands in your major mode, and
     ;; then use `\\{...}' to display the rest of the mode's keymap.
     (save-excursion
       (if (re-search-forward "\\\\\\\\\\[\\w+" e t
			      (1+ checkdoc-max-keyref-before-warn))
	   "Too many occurrences of \\[function].  Use \\{keymap} instead"))
     ;; Ambiguous quoted symbol.  When a symbol is both bound and fbound,
     ;; and is referred to in documentation, it should be prefixed with
     ;; something to disambiguate it.  This check must be before the
     ;; 80 column check because it will probably break that.
     (save-excursion
       (let ((case-fold-search t)

		 (setq ms (substring ms 0 (1- (length ms))))))
	   (if (and (not (checkdoc-in-sample-code-p start e))
		    (setq found (intern-soft ms))
		    (or (boundp found) (fboundp found)))
	       (progn
		 (setq msg (format "Add quotes around Lisp symbol `%s'? "
				   ms))
		 (if (checkdoc-autofix-ask-replace
		      (match-beginning 1) (+ (match-beginning 1)
					     (length ms))
		      msg (concat "`" ms "'") t)

     ;; t and nil case
     (save-excursion
       (if (re-search-forward "\\(`\\(t\\|nil\\)'\\)" e t)
	   (if (checkdoc-autofix-ask-replace
		(match-beginning 1) (match-end 1)
		(format "%s should not appear in quotes.  Remove? "
			(match-string 2))
		(match-string 2) t)
	       nil
	     "Symbols t and nil should not appear in `quotes'")))
     ;; Here we deviate to tests based on a variable or function.

	     ;;   condition, give it a name that ends in `-flag'.

	     ;; If the variable has -flag in the name, make sure
	     (if (and (string-match "-flag$" (car fp))
		      (not (looking-at "\"\\*?Non-nil\\s-+means\\s-+")))
		 "Flag variable doc strings should start: Non-nil means")
	     ;; If the doc string starts with "Non-nil means"
	     (if (and (looking-at "\"\\*?Non-nil\\s-+means\\s-+")
		      (not (string-match "-flag$" (car fp))))
		 "Flag variables should end in `-flag'")
	     ;; Done with variables
	     ))
	   (t
	    ;; This if we are in a function definition
	    (or

					  "\\)\\(\\>\\|th\\>\\|s\\>\\)")
				  e t))
			     (if (checkdoc-autofix-ask-replace
				  (match-beginning 1) (match-end 1)
				  (format
				   "Argument `%s' should appear as `%s'.  Fix? "
				   (car args) (upcase (car args)))
				  (upcase (car args)) t)
				 (setq found (match-beginning 1))))))
		   (if found (setq args (cdr args)))))
	       (if (not found)
		   ;; It wasn't found at all!  Offer to attach this new symbol
		   ;; to the end of the documentation string.
		   (if (y-or-n-p
			(format "Add %s documentation to end of doc string?"
				(upcase (car args))))
		       ;; Now do some magic and invent a doc string.
		       (save-excursion
			 (goto-char e) (forward-char -1)
			 (insert "\n"
				 (if inopts "Optional a" "A")
				 "rgument " (upcase (car args))

			 (if (not (save-excursion (forward-char -1)
						  (looking-at "[.?!]")))
			     (insert "."))
			 nil)
		     (format
		      "Argument `%s' should appear as `%s' in the doc string"
		      (car args) (upcase (car args))))
		 (if (or (and order (eq order 'yes))
			 (and (not order) checkdoc-arguments-in-order-flag))
		     (if (< found last-pos)
			 "Arguments occur in the doc string out of order"))))
	     ;; Done with functions
	     )))
     ;; Make sure the doc string has correctly spelled english words
     ;; in it.  This functions is extracted due to its complexity,
     ;; and reliance on the Ispell program.
     (checkdoc-ispell-docstring-engine e)
     ;; User supplied checks
     (save-excursion (checkdoc-run-hooks 'checkdoc-style-hooks fp e))
     ;; Done!
     )))

(defun checkdoc-defun-info nil
  "Return a list of details about the current sexp.
It is a list of the form:
   (NAME VARIABLE INTERACTIVE NODOCPARAMS PARAMETERS ...)
where NAME is the name, VARIABLE is t if this is a `defvar',
INTERACTIVE is nil if this is not an interactive function, otherwise
it is the position of the `interactive' call, and PARAMETERS is a
string which is the name of each variable in the function's argument
list.  The NODOCPARAMS is a sublist of parameters specified by a checkdoc

	    (setq ret (cons (symbol-name (car lst)) ret)
		  lst (cdr lst)))))
      (nreverse ret))))

(defun checkdoc-in-sample-code-p (start limit)
  "Return non-nil if the current point is in a code fragment.
A code fragment is identified by an open parenthesis followed by a
symbol which is a valid function, or a parenthesis that is quoted with the '
character.  Only the region from START to LIMIT is is allowed while
searching for the bounding parenthesis."
  (save-match-data

;;; Ispell engine
;;
(eval-when-compile (require 'ispell))

(defun checkdoc-ispell-init ()
  "Initialize Ispell process (default version) with Lisp words.
The words used are from `checkdoc-ispell-lisp-words'.  If `ispell'
cannot be loaded, then set `checkdoc-spellcheck-documentation-flag' to
nil."
  (require 'ispell)
  (if (not (symbol-value 'ispell-process)) ;Silence byteCompiler
      (condition-case nil
	  (progn
	    (ispell-buffer-local-words)
	    ;; This code copied in part from ispell.el Emacs 19.34
	    (let ((w checkdoc-ispell-lisp-words))
	      (while w
		(process-send-string
		 ;;  Silence byte compiler
		 (symbol-value 'ispell-process)
		 (concat "@" (car w) "\n"))
		(setq w (cdr w)))))
	(error (setq checkdoc-spellcheck-documentation-flag nil)))))

(defun checkdoc-ispell-docstring-engine (end)
  "Run the Ispell tools on the doc string between point and END.
Since Ispell isn't Lisp-smart, we must pre-process the doc string
before using the Ispell engine on it."
  (if (not checkdoc-spellcheck-documentation-flag)
      nil
    (checkdoc-ispell-init)
    (save-excursion
      (skip-chars-forward "^a-zA-Z")

Some editors & news agents may remove it")))
     ;; Check for, and pottentially remove whitespace appearing at the
     ;; end of different lines.
     (progn
       (goto-char start)
       ;; There is no documentation in the Emacs Lisp manual about this check,
       ;; it is intended to help clean up messy code and reduce the file size.
       (while (and (not msg) (re-search-forward "[^ \t\n]\\([ \t]+\\)$" end t))
	 ;; This is not a complex activity
	 (if (checkdoc-autofix-ask-replace
	      (match-beginning 1) (match-end 1)
	      "White space at end of line.  Remove? " "")
	     nil
	   (setq msg "White space found at end of line")))))
    ;; Return an error and leave the cursor at that spot, or restore
    ;; the cursor.
    (if msg

  ;; a) get symbols for comple and
  ;; b) determine if we have lm-history symbol which doesn't always exist
  (require 'lisp-mnt))

(defun checkdoc-file-comments-engine ()
  "Return a message string if this file does not match the Emacs standard.
This checks for style only, such as the first line, Commentary:,
Code:, and others referenced in the style guide."
  (if (featurep 'lisp-mnt)
      nil
    (require 'lisp-mnt)

	   (let ((complex-replace t))
	     (while (looking-at ";;\\(;\\)[^;]")
	       (if (and (checkdoc-outside-major-sexp) ;in code is ok.
			(checkdoc-autofix-ask-replace
			 (match-beginning 1) (match-end 1)
			 "Multiple occurances of ;;; found.  Use ;; instead? "
			 "" complex-replace))
		   ;; Learn that, yea, the user did want to do this a
		   ;; whole bunch of times.
		   (setq complex-replace nil))
	       (beginning-of-line)

       ;; visible section (with the finder)
       (save-excursion
	 (goto-char (lm-commentary-mark))
	 ;; Spellcheck between the commentary, and the first
	 ;; non-comment line.  We could use lm-commentary, but that
	 ;; returns a string, and Ispell wants to talk to a buffer.
	 ;; Since the comments talk about Lisp, use the specialized
	 ;; spell-checker we also used for doc strings.
	 (checkdoc-ispell-docstring-engine (save-excursion
					     (re-search-forward "^[^;]" nil t)
					     (point))))
;;; test comment out code
;;;       (foo 1 3)

		 (beginning-of-line)))
    (other-window -1)
    (shrink-window-if-larger-than-buffer)))

(defgroup checkdoc nil
  "Support for doc string checking in Emacs Lisp."
  :prefix "checkdoc"
  :group 'lisp
  :version "20.3")

(custom-add-option 'emacs-lisp-mode-hook
		   (lambda () (checkdoc-minor-mode 1)))

(provide 'checkdoc)

;;; checkdoc.el ends here