Re[3]: doc-strings in src/ and the first line

[Eric M. Ludlam]

>>> "Eric M. Ludlam" <address@hidden> seems to think that:
>>>> "Eli Zaretskii" <address@hidden> seems to think that:
>>> Date: Thu, 15 Nov 2001 18:03:19 -0500
>>> From: "Eric M. Ludlam" <address@hidden>
>>> 
>>> I searched around once, and posted a question to a newsgroup on how to
>>> possibly link the byte compiler to produce checkdoc warnings for bad
>>> doc-strings at compile time but came up empty.  Is that the sort of
>>> project you are thinking of?
>>
>>What I had in mind is some kind of batch command that could be run
>>from a Makefile, which would produce a warning about bad doc
>>strings.  Adding such a feature to the byte compiler would also be
>>useful, but the original motivation for this thread was the doc
>>strings in C sources, not in Lisp files.
>  [ ... ]
>
>That should be possible.  After all, byte compilation is done during
>the Make phase.  Why not checkdoc?  I already posted a Lisp snippet to
>doc-check one entry from a DOC file.  I'll adapt it to pump out
>warning lists for the whole thing over the holiday.  It'll be fuggly
>but functional.  At least it will keep everyone busy. ;)
  [ ... ]

Ok, so I didn't wait for the holiday.

The below code will check the doc strings of everything in the DOC
file.  This takes a couple minutes on my 300 Mhz machine, and produced
2146 warnings.  Unfortunately, 1113 of them are asking about escaping
a ( in column 0 which seems to be a new test I wasn't aware of, so I
added "Addendum: " to the comment in my copy of checkdoc.  There are
also a few erroneous warnings due to a lack of regular string
quoting.  Oy.

To make this more usable, the warning buffer should display the
symbol the documentation is associated with, but that may require
patches to core checkdoc. 

Have Fun
Eric

(defun checkdoc-built-in-functions ()
  "Check the documentation strings for all built-in functions and variables.
The documentation for these entries are all in the DOC file created at
build time.  This utility works by converting these entries into cheesy
Lisp, and running the checkdoc engine in log mode."
  (interactive)
  (save-window-excursion
    (message "Converting DOC to Emacs Lisp representation...")
    (checkdoc-convert-DOC-to-cheesy-lisp)
    (message "Style Checking...")
    (checkdoc-current-buffer t)
    )
  (pop-to-buffer checkdoc-diagnostic-buffer))

(defun checkdoc-convert-DOC-to-cheesy-lisp ()
  "Convert the current buffer in DOC format to cheesy-Lisp."
  (set-buffer (get-buffer-create "DOC-convert.el"))
  (erase-buffer)
  (insert-file-contents
   (concat doc-directory internal-doc-file-name))
  (goto-char (point-min))
  (let ((emacs-lisp-mode-hook nil)
        (global-font-lock-mode nil))
    (emacs-lisp-mode))
  ;; Convert each individual entry in the DOC file to psuedo lisp.
  (while (re-search-forward "\C-_" nil t)
    (cond ((looking-at "_F")            ;A function
           (beginning-of-line)
           (insert "(defun ")
           (delete-char 1)
           (forward-sexp 1)
           (skip-syntax-forward "-")
           (insert " (")
           (re-search-forward ")")
           (delete-region (point) (progn (forward-sexp 1) (point)))
           (forward-char 1)
           )
          (t                            ;a variable
           (forward-char -1)
           (insert "\n(defvar ")
           (delete-char 2)
           (end-of-line)
           (insert " nil")
           (forward-char 1)
           ))
    (insert "\"")
    (if (not (re-search-forward "\C-_" nil t))
        (goto-char (point-max)))
    (if (looking-at "_F")
        (progn
          (beginning-of-line)
          (forward-line -1)
          (forward-char -1))
      (forward-char -1))
    (insert "\")\n")
    )
  )