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

[Pavel Janík]

   From: Eli Zaretskii <address@hidden>
   Date: Wed, 14 Nov 2001 13:36:10 +0200 (IST)

   > > It is embarrassing that we had accumulated so many mistakes.
   > 
   > How about writing something for src/Makefile.in which would find such 
   > mistakes?  Any takers?

We already have this check implemented in checkdoc (but it can only check
for these bugs in elisp files). BTW - if anyone considers creating such
Makefile target: what about checking only the contents of the DOC file
directly (or make-docfile.c)? It should be quite straightforward then.

Hmm, when this mail was in my outgoing queue, I gave it a try. I did not
wanted to spend more than 10 minutes on it, so here is a result:

check_first_line
Description: Binary data

It is of course not perfect, but I do not think it is worthy to invest my
time to this (`.)' is sometimes correct end of sentence, etc.)

Its output now is as follows. I have marked cases which are here because
of bugs in make-docfile:

Vdos-display-scancodes: *When non-nil, the keyboard scan-codes are displayed at 
the bottom right
Vdos-decimal-point: If non-zero, it contains the character to be returned when 
the
Vface-new-frame-defaults: List of global face definitions (for internal use 
only.)
Vdefining-kbd-macro: Non-nil while a keyboard macro is being defined.  Don't 
set this!
Ffile-exists-p: Return t if file FILENAME exists.  (This does not mean you can 
read it.)
FSnarf-documentation: Used during Emacs initialization, before dumping runnable 
Emacs,
>>> Fml-prefix-argument-loop: usage: (ml-prefix-argument-loop ...)

   ... make-docfile does not accept usage: on the same line as the
   beginning of the comment `doc: /* '.

Vmouse-buffer-menu-mode-mult: *Group the buffers by the major mode groups on 
\[mouse-buffer-menu]?
Fx-get-cut-buffer: Returns the value of one of the 8 X server cut-buffers.  
Optional arg

>>> Fxselect-convert-to-class: Emacs
>>> Fxselect-convert-to-name: emacs

   ... Both are functions which return only string. They do not have
   doc-strings, but make-docfile takes theirs return value as one.

Fstart-subprocess: Spawns an asynchronous subprocess with output redirected to
Fcommand-send-input: If at last line of buffer, sends the current line to
Fls-lisp-extension: Return extension of FILENAME (ignoring any version 
extension)
Vuntranslated-filesystem-list: List of filesystems that require no CR/LF 
translation when reading 
Funtranslated-canonical-name: Return FILENAME in a canonicalized form for use 
with the functions
Funtranslated-file-p: Return t if FILENAME is on a filesystem that does not 
require 
Fadd-untranslated-filesystem: Add FILESYSTEM to the list of filesystems that do 
not require
Fremove-untranslated-filesystem: Remove FILESYSTEM from the list of filesystems 
that do not require 
Vdos-codepage-setup-hook: *List of functions to be called after the DOS 
terminal and coding
Fcp-decoding-vector-for-codepage: Create a vector for decoding IBM PC 
characters using conversion table
Vcp1250-decode-table: ISO-8859-2 to Windows-1250 (Central Europe) codepage 
decoding table
Vcp1251-decode-table: ISO-8859-5 to Windows-1251 (Cyrillic) codepage decoding 
table
Vcp1253-decode-table: ISO-8859-7 to Windows-1253 (Greek) codepage decoding table
Vcp1257-decode-table: ISO-8859-4 to Windows-1257 (Baltic) codepage decoding 
table
Fcp-make-coding-systems-for-codepage: Create a coding system to convert IBM 
CODEPAGE into charset ISO-NAME
Fcp-codepage-decoder: If CODEPAGE is the name of a supported codepage, return 
its decode table;
FBuffer-menu-delete-backwards: Mark buffer on this line to be deleted by 
\<Buffer-menu-mode-map>\[Buffer-menu-execute] command
Fmake-obsolete-variable: Make the byte-compiler warn that VARIABLE is obsolete,
Vfacemenu-keybindings: Alist of interesting faces and keybindings. 
Vpi: The value of Pi (3.1415926...)
Ve: The value of e (2.7182818...)
Vdegrees-to-radians: Degrees to radian conversion constant
Vradians-to-degrees: Radian to degree conversion constant
Fhelp-for-help-doc: You have typed %THIS-KEY%, the help character.  Type a Help 
option:
Vedit-tab-stops-buffer: Buffer whose tab stops are being edited--in case
Fisearch-delete-char: Discard last input item and move point back.  
F5x5-crack-xor-mutate: Attempt to crack 5x5 by xor the current and best 
solution and then
Fupdate-file-autoloads: Update the autoloads for FILE in 
`generated-autoload-file'
Fblackbox: Play blackbox.  Optional prefix argument is the number of balls;
Fcp-make-coding-systems-for-codepage: Create a coding system to convert IBM 
CODEPAGE into charset ISO-NAME
Fcookie: Return a random phrase from PHRASE-FILE.  When the phrase file
Fcookie-insert: Insert random phrases from PHRASE-FILE; COUNT of them.  When 
the phrase file
Fshuffle-vector: Randomly permute the elements of VECTOR (all permutations 
equally likely)
Fcopyright-update: Update the copyright notice at the beginning of the buffer 
to indicate
Fdelphi-mode: Major mode for editing Delphi code. \<delphi-mode-map>
Fdevanagari-decompose-string: Decompose Devanagari string STR
Fediff-directories: Run Ediff on a pair of directories, DIR1 and DIR2, 
comparing files that have
Fediff-directories3: Run Ediff on three directories, DIR1, DIR2, and DIR3, 
comparing files that
Fediff-merge-directories: Run Ediff on a pair of directories, DIR1 and DIR2, 
merging files that have
Ffind-name-dired: Search DIR recursively for files matching the globbing 
pattern PATTERN,
Fgnus-group-split-update: Computes nnmail-split-fancy from group params and 
CATCH-ALL, by
Fgnus-group-split-fancy: Uses information from group parameters in order to 
split mail.  It
Fjdb: Run jdb with command line COMMAND-LINE in a buffer.  The buffer is named
Fispell-complete-word: Try to complete the word before or under point (see 
`lookup-words')
Fapply-macro-to-region-lines: For each complete line between point and mark, 
move to the beginning
Fmh-letter-mode: Mode for composing letters in mh-e.\<mh-letter-mode-map>
Fminibuffer-electric-default-mode: Toggle Minibuffer Electric Default mode
Fpascal-mode: Major mode for editing Pascal code. \<pascal-mode-map>
Fps-line-lengths: Display the correspondence between a line length and a font 
size, using the
Vquickurl-reread-hook-postfix: Example `quickurl-postfix' text that adds a 
local variable to the
Fread-file-name-electric-shadow-mode: Toggle Read-File-Name Electric Shadow mode
Vrmail-default-dont-reply-to-names: A regular expression specifying part of the 
value of the default value of
Vshell-dumb-shell-regexp: Regexp to match shells that don't save their command 
history, and
Fstudlify-region: Studlify-case the region
Fstudlify-word: Studlify-case the current word, or COUNT words if given an 
argument
Fwhitespace-write-file-hook: The local-write-file-hook to be called on the 
buffer when
Fzone-mode-update-serial-hook: Update the serial number in a zone if the file 
was modified
Vtibetan-precomposition-rule-regexp: Regexp string to match a sequence of 
Tibetan consonantic components, i.e.,
Vterm-file-prefix: If non-nil, Emacs startup does (load (concat 
term-file-prefix (getenv "TERM")))
Finsert-register: Insert contents of register REGISTER.  (REGISTER is a 
character.)
Fset-mark: Set this buffer's mark to POS.  Don't use this function!
Vcommand-line-processed: Non-nil once command line has been processed
Vctl-x-4-map: Keymap for subcommands of C-x 4
Ftty-color-approximate: Given a list of 3 rgb values in RGB, find the color in 
`tty-color-alist'
Fcurrent-justification: How should we justify this line?
Fset-justification-right: Make paragraphs in the region right-justified:
Fset-justification-full: Make paragraphs in the region fully justified:
Fvc-check-master-templates: Return non-nil if there is a master corresponding 
to FILE,
Fvc-default-make-version-backups-p: Return non-nil if unmodified repository 
versions should 

-- 
Pavel Janík

But for the user this does not matter, he just sees a frozen
machine. Even if it would recover in some hours ;)
                  -- Hubert Mantel