Function: checkdoc-file-comments-engine

checkdoc-file-comments-engine is a byte-compiled function defined in checkdoc.el.gz.

Signature

(checkdoc-file-comments-engine)

Documentation

Return a message list 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.

Source Code

;; Defined in /usr/src/emacs/lisp/emacs-lisp/checkdoc.el.gz
(defun checkdoc-file-comments-engine ()
  "Return a message list 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."
  (save-excursion
    (let* ((f1 (file-name-nondirectory (buffer-file-name)))
	   (fn (file-name-sans-extension f1))
	   (fe (substring f1 (length fn)))
	   (err nil))
      (goto-char (point-min))
      ;; This file has been set up where ERR is a variable.  Each check is
      ;; asked, and the function will make sure that if the user does not
      ;; auto-fix some error, that we still move on to the next auto-fix,
      ;; AND we remember the past errors.
      (setq
       err
       ;; Lisp Maintenance checks first
       ;; Was: (lm-verify) -> not flexible enough for some people
       ;; * Summary at the beginning of the file:
       (if (not (lm-summary))
	   ;; This certifies as very complex so always ask unless
	   ;; it's set to never
           (if (checkdoc-y-or-n-p "There is no first line summary!  Add one?")
	       (progn
		 (goto-char (point-min))
		 (insert ";;; " fn fe " --- " (read-string "Summary: ") "\n"))
	     (checkdoc-create-error
	      "The first line should be of the form: \";;; package --- Summary\""
	      (point-min) (save-excursion (goto-char (point-min))
					  (line-end-position))))
	 nil))
      (setq
       err
       (or
	;; * Commentary Section
        (if (and (not (lm-commentary-mark))
                 ;; No need for a commentary section in test files.
                 (not (string-match
                       (rx (or (seq (or "-test.el" "-tests.el") string-end)
                               "/test/" "/tests/"))
                       (buffer-file-name))))
            (progn
	      (goto-char (point-min))
	      (cond
	       ((re-search-forward
		 "write\\s-+to\\s-+the\\s-+Free Software Foundation, Inc."
		 nil t)
		(re-search-forward "^;;\\s-*\n\\|^\n" nil t))
	       ((or (re-search-forward "^;;; History" nil t)
		    (re-search-forward "^;;; Code" nil t)
		    (re-search-forward "^(require" nil t)
		    (re-search-forward "^(" nil t))
		(beginning-of-line))
	       ((not (re-search-forward ";;; .* --- .*\n" nil t))
                (checkdoc-create-error
                 "You should have a summary line (\";;; .* --- .*\")"
                 nil nil t)))
	      (if (checkdoc-y-or-n-p
                   "You should have a \";;; Commentary:\", add one?")
		  (insert "\n;;; Commentary:\n;; \n\n")
		(checkdoc-create-error
		 "You should have a section marked \";;; Commentary:\""
		 nil nil t)))
	  nil)
	err))
      (setq
       err
       (or
	;; * History section.  Say nothing if there is a file ChangeLog
	(if (or (not checkdoc-force-history-flag)
		(file-exists-p "ChangeLog")
		(file-exists-p "../ChangeLog")
                (lm-history-mark))
	    nil
	  (progn
	    (goto-char (or (lm-commentary-mark) (point-min)))
	    (cond
	     ((re-search-forward
	       "write\\s-+to\\s-+the\\s-+Free Software Foundation, Inc."
	       nil t)
	      (re-search-forward "^;;\\s-*\n\\|^\n" nil t))
	     ((or (re-search-forward "^;;; Code" nil t)
		  (re-search-forward "^(require" nil t)
		  (re-search-forward "^(" nil t))
	      (beginning-of-line)))
	    (if (checkdoc-y-or-n-p
                 "You should have a \";;; History:\", add one?")
		(insert "\n;;; History:\n;; \n\n")
	      (checkdoc-create-error
	       "You should have a section marked \";;; History:\" or use a ChangeLog"
	       (point) nil))))
	err))
      (setq
       err
       (or
	;; * Code section
	(if (not (lm-code-mark))
	    (let ((cont t)
		  pos)
	      (goto-char (point-min))
	      ;; match ";;;###autoload" cookie to keep it with the form
	      (require 'autoload)
	      (while (and cont (re-search-forward
				(concat "^\\("
					(regexp-quote generate-autoload-cookie)
					"\n\\)?"
					"(")
				nil t))
		(setq pos (match-beginning 0)
		      cont (looking-at "require\\s-+")))
	      (if (and (not cont)
		       (checkdoc-y-or-n-p
                        "There is no ;;; Code: marker.  Insert one?"))
		  (progn (goto-char pos)
			 (insert ";;; Code:\n\n")
			 nil)
		(checkdoc-create-error
		 "You should have a section marked \";;; Code:\""
		 (point) nil)))
	  nil)
	err))
      (setq
       err
       (or
	;; * A footer.  Not compartmentalized from lm-verify: too bad.
	;;              The following is partially clipped from lm-verify
	(save-excursion
	  (goto-char (point-max))
	  (if (not (re-search-backward
                    ;; This should match the requirement in
                    ;; `package-buffer-info'.
                    (concat "^;;; " (regexp-quote (concat fn fe)) " ends here")
		    nil t))
              (if (checkdoc-y-or-n-p "No identifiable footer!  Add one?")
		  (progn
		    (goto-char (point-max))
		    (insert "\n(provide '" fn ")\n\n;;; " fn fe " ends here\n"))
		(checkdoc-create-error
		 (format "The footer should be: (provide '%s)\\n;;; %s%s ends here"
			 fn fn fe)
                 ;; The buffer may be empty.
		 (max (point-min) (1- (point-max)))
                 (point-max)))))
	err))
      ;; The below checks will not return errors if the user says NO

      ;; Let's spellcheck the commentary section.  This is the only
      ;; section that is easy to pick out, and it is also the most
      ;; visible section (with the finder).
      (let ((cm (lm-commentary-mark)))
        (when cm
          (save-excursion
            (goto-char cm)
            (let ((e (copy-marker (lm-commentary-end))))
              ;; Since the comments talk about Lisp, use the
              ;; specialized spell-checker we also used for doc
              ;; strings.
              (checkdoc-sentencespace-region-engine (point) e)
              (checkdoc-proper-noun-region-engine (point) e)
              (checkdoc-ispell-docstring-engine e)))))
      (setq
       err
       (or
	;; Generic Full-file checks (should be comment related)
	(run-hook-with-args-until-success 'checkdoc-comment-style-functions)
	err))
      ;; Done with full file comment checks
      err)))