comparison lisp/emacs-lisp/checkdoc.el @ 20603:24dda0afd915

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'.

20602:e8566ea47491

;;; checkdoc --- Check documentation strings for style requirements

;;;  Copyright (C) 1997  Free Software Foundation, Inc.
;;
;; Author: Eric M. Ludlam <[e-mail]>
;; Version: 0.4.1
;; Keywords: docs, maint, lisp
;;
;; This file is part of GNU Emacs.

;; GNU Emacs is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 2, or (at your option)
;; any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING.  If not, write to the
;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.

;; 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.
;;
;; Adding your own checks:
;;
;;   You can experiment with adding your own checks by setting the
;; hooks `checkdoc-style-hooks' and `checkdoc-comment-style-hooks'.

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

;;; 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

;;   Code sweep checks for "forbidden functions", proper use of hooks,
;;     proper keybindings, and other items from the manual that are
;;     not specifically docstring related.  Would this even be useful?

;;; Code:
(defvar checkdoc-version "0.4.1"
  "Release version of checkdoc you are currently running.")

;; From custom web page for compatibility between versions of custom:
(eval-and-compile
  (condition-case ()

    ;; We have the old custom-library, hack around it!
    (defmacro defgroup (&rest args)
      nil)
    (defmacro custom-add-option (&rest args)
      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

  "Hooks called after the standard comment style check is completed.
Must return nil if no errors are found, or a string describing the
problem discovered.  This is useful for adding additional checks.")

(defvar checkdoc-diagnostic-buffer "*Style Warnings*"
  "Name of the buffer where checkdoc stores warning messages.")

(defvar checkdoc-defun-regexp
  "^(def\\(un\\|var\\|custom\\|macro\\|const\\|subst\\|advice\\)\
\\s-+\\(\\(\\sw\\|\\s_\\)+\\)[ \t\n]+"
  "Regular expression used to identify a defun.

		   replace original)))))
     ;;   * Don't write key sequences directly in documentation strings.
     ;;     Instead, use the `\\[...]' construct to stand for them.
     (save-excursion
       (let ((f nil) (m nil) (start (point))
	     (re "\\<\\([CMA]-[a-zA-Z]\\|\\(\\([CMA]-\\)?\
mouse-[0-3]\\)\\)\\>"))
	 ;; Find the first key sequence not in a sample
	 (while (and (not f) (setq m (re-search-forward re e t)))
	   (setq f (not (checkdoc-in-sample-code-p start e))))
	 (if m

	    (if (and sym (or (boundp sym) (fboundp sym)))
		;; This is probably repetative in most cases, but not always.
		nil
	      ;; Find out how we spell-check this word.
	      (if (or
		   (not (string-match "[a-z]" word)) ;all caps meta variable
		   (looking-at "}") ; a keymap expression
		   )
		  nil
		(save-excursion
		  (if (not (eq checkdoc-autofix-flag 'never))

20603:24dda0afd915

;;; checkdoc --- Check documentation strings for style requirements

;;;  Copyright (C) 1997, 1998  Free Software Foundation
;;
;; Author: Eric M. Ludlam <[e-mail]>
;; Version: 0.4.2
;; Keywords: docs, maint, lisp
;;
;; This file is part of GNU Emacs.
;;
;; GNU Emacs is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 2, or (at your option)
;; any later version.
;;
;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.
;;
;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING.  If not, write to the
;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.

;; 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 might not always want a function to have it's 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)"
;;
;; Adding your own checks:
;;
;;   You can experiment with adding your own checks by setting the
;; hooks `checkdoc-style-hooks' and `checkdoc-comment-style-hooks'.

;;       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'.

;;; 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

;;   Code sweep checks for "forbidden functions", proper use of hooks,
;;     proper keybindings, and other items from the manual that are
;;     not specifically docstring related.  Would this even be useful?

;;; Code:
(defvar checkdoc-version "0.4.2"
  "Release version of checkdoc you are currently running.")

;; From custom web page for compatibility between versions of custom:
(eval-and-compile
  (condition-case ()

    ;; We have the old custom-library, hack around it!
    (defmacro defgroup (&rest args)
      nil)
    (defmacro custom-add-option (&rest args)
      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

  "Hooks called after the standard comment style check is completed.
Must return nil if no errors are found, or a string describing the
problem discovered.  This is useful for adding additional checks.")

(defvar checkdoc-diagnostic-buffer "*Style Warnings*"
  "Name of warning message buffer.")

(defvar checkdoc-defun-regexp
  "^(def\\(un\\|var\\|custom\\|macro\\|const\\|subst\\|advice\\)\
\\s-+\\(\\(\\sw\\|\\s_\\)+\\)[ \t\n]+"
  "Regular expression used to identify a defun.

		   replace original)))))
     ;;   * Don't write key sequences directly in documentation strings.
     ;;     Instead, use the `\\[...]' construct to stand for them.
     (save-excursion
       (let ((f nil) (m nil) (start (point))
	     (re "[^`]\\([CMA]-[a-zA-Z]\\|\\(\\([CMA]-\\)?\
mouse-[0-3]\\)\\)\\>"))
	 ;; Find the first key sequence not in a sample
	 (while (and (not f) (setq m (re-search-forward re e t)))
	   (setq f (not (checkdoc-in-sample-code-p start e))))
	 (if m

	    (if (and sym (or (boundp sym) (fboundp sym)))
		;; This is probably repetative in most cases, but not always.
		nil
	      ;; Find out how we spell-check this word.
	      (if (or
		   ;; All caps w/ option th, or s tacked on the end
		   ;; for pluralization or nuberthness.
		   (string-match "^[A-Z][A-Z]+\\(s\\|th\\)?$" word)
		   (looking-at "}") ; a keymap expression
		   )
		  nil
		(save-excursion
		  (if (not (eq checkdoc-autofix-flag 'never))