Added or corrected Commentary sections

lisp/abbrev.el

@@ -20,6 +20,10 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; This facility is documented in the Emacs Manual.
+
 ;;; Code:
 
 (defconst only-global-abbrevs nil "\

lisp/ada.el

@@ -166,8 +166,8 @@ Variable `ada-indent' controls the number of spaces for indent/undent."
   (setq comment-column 41)
   (make-local-variable 'comment-start-skip)
   (setq comment-start-skip "--+ *")
-  (make-local-variable 'comment-indent-hook)
-  (setq comment-indent-hook 'c-comment-indent)
+  (make-local-variable 'comment-indent-function)
+  (setq comment-indent-function 'c-comment-indent)
   (make-local-variable 'parse-sexp-ignore-comments)
   (setq parse-sexp-ignore-comments t)
   (run-hooks 'ada-mode-hook))

lisp/add-log.el

@@ -20,6 +20,10 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; This facility is documented in the Emacs Manual.
+
 ;;; Code:
 
 ;;;###autoload

lisp/array.el

@@ -24,14 +24,18 @@
 
 ;;; Commentary:
 
-;;;  Written by dmb%morgoth@harvard.harvard.edu (address is old)
-;;;   (David M. Brown at Goldberg-Zoino & Associates, Inc.)
-;;;  Thanks to cph@kleph.ai.mit.edu for assistance
-
-;;; To do:
-;;;   Smooth initialization process by grokking local variables list
-;;;     at end of buffer or parsing buffer using whitespace as delimiters.
-;;;   Make 'array-copy-column-right faster.
+;; Commands for editing a buffer interpreted as a rectangular array
+;; or matrix of whitespace-separated strings.  You specify the array
+;; dimensions and some other parameters at startup time.
+
+;;  Written by dmb%morgoth@harvard.harvard.edu (address is old)
+;;   (David M. Brown at Goldberg-Zoino & Associates, Inc.)
+;;  Thanks to cph@kleph.ai.mit.edu for assistance
+
+;; To do:
+;;   Smooth initialization process by grokking local variables list
+;;     at end of buffer or parsing buffer using whitespace as delimiters.
+;;   Make 'array-copy-column-right faster.
 
 
 ;;; Code:

lisp/autoinsert.el

@@ -49,8 +49,6 @@
 ;;;           Duke University Medical Center
 ;;;           Durham, NC 27710
 ;;;	      (crm@cs.duke.edu,mcnc!duke!crm) 
-;;;
-;;;  Date: Fri Jul  1 16:15:31 EDT 1988
 
 ;;; Code:
 

lisp/buff-menu.el

@@ -20,6 +20,13 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; Edit, delete, or change attributes of all currently active Emacs
+;; buffers from a list summarizing thir state.  A good way to browse
+;; any special or scratch buffers you have loaded, since you can't find
+;; them by filename.
+
 ;;; Code:
 
 ; Put buffer *Buffer List* into proper mode right away

lisp/cmulisp.el

@@ -72,62 +72,65 @@
 ;;       '((lambda () 
 ;;           (define-key cmulisp-mode-map "\C-ct" 'favorite-cmd))))
 
-
-;;; Brief Command Documentation:
-;;;============================================================================
-;;; Comint Mode Commands: (common to cmulisp and all comint-derived modes)
-;;;
-;;; m-p	    comint-previous-input    	    Cycle backwards in input history
-;;; m-n	    comint-next-input  	    	    Cycle forwards
-;;; m-c-r   comint-previous-input-matching  Search backwards in input history
-;;; return  comint-send-input
-;;; c-a     comint-bol                      Beginning of line; skip prompt.
-;;; c-d	    comint-delchar-or-maybe-eof	    Delete char unless at end of buff.
-;;; c-c c-u comint-kill-input	    	    ^u
-;;; c-c c-w backward-kill-word    	    ^w
-;;; c-c c-c comint-interrupt-subjob 	    ^c
-;;; c-c c-z comint-stop-subjob	    	    ^z
-;;; c-c c-\ comint-quit-subjob	    	    ^\
-;;; c-c c-o comint-kill-output		    Delete last batch of process output
-;;; c-c c-r comint-show-output		    Show last batch of process output
-;;;         send-invisible                  Read line w/o echo & send to proc
-;;;         comint-continue-subjob	    Useful if you accidentally suspend
-;;;					        top-level job.
-;;; comint-mode-hook is the comint mode hook.
-
-;;; CMU Lisp Mode Commands:
-;;; c-m-x   lisp-send-defun     This binding is a gnu convention.
-;;; c-c c-l lisp-load-file  	Prompt for file name; tell Lisp to load it.
-;;; c-c c-k lisp-compile-file	Prompt for file name; tell Lisp to kompile it.
-;;; 	    	    	    	Filename completion is available, of course.
-;;;
-;;; Additionally, these commands are added to the key bindings of Lisp mode:
-;;; c-m-x   lisp-eval-defun         This binding is a gnu convention.
-;;; c-c c-e lisp-eval-defun 	    Send the current defun to Lisp process.
-;;; c-x c-e lisp-eval-last-sexp     Send the previous sexp to Lisp process.
-;;; c-c c-r lisp-eval-region        Send the current region to Lisp process.
-;;; c-c c-c lisp-compile-defun      Compile the current defun in Lisp process.
-;;; c-c c-z switch-to-lisp          Switch to the Lisp process buffer.
-;;; c-c c-l lisp-load-file          (See above. In a Lisp file buffer, default
-;;; c-c c-k lisp-compile-file        is to load/compile the current file.)
-;;; c-c c-d lisp-describe-sym	    Query Lisp for a symbol's description.
-;;; c-c c-a lisp-show-arglist	    Query Lisp for function's arglist.
-;;; c-c c-f lisp-show-function-documentation Query Lisp for a function's doc.
-;;; c-c c-v lisp-show-variable-documentation Query Lisp for a variable's doc.
-
-;;; cmulisp	    	    	    Fires up the Lisp process.
-;;; lisp-compile-region     	    Compile all forms in the current region.
-;;;
-;;; CMU Lisp Mode Variables:
-;;; cmulisp-filter-regexp	    Match this => don't get saved on input hist
-;;; inferior-lisp-program   	    Name of Lisp program run-lisp executes
-;;; inferior-lisp-load-command	    Customises lisp-load-file
-;;; cmulisp-mode-hook  	    
-;;; inferior-lisp-prompt	    Initialises comint-prompt-regexp.
-;;;				    Backwards compatibility.
-;;; lisp-source-modes               Anything loaded into a buffer that's in
-;;;                                 one of these modes is considered Lisp 
-;;;                                 source by lisp-load/compile-file.
+;; Brief Command Documentation:
+;;============================================================================
+;; Comint Mode Commands: (common to cmulisp and all comint-derived modes)
+;;
+;; m-p	    comint-previous-input    	    Cycle backwards in input history
+;; m-n	    comint-next-input  	    	    Cycle forwards
+;; m-c-r   comint-previous-input-matching  Search backwards in input history
+;; return  comint-send-input
+;; c-a     comint-bol                      Beginning of line; skip prompt.
+;; c-d	    comint-delchar-or-maybe-eof	    Delete char unless at end of buff.
+;; c-c c-u comint-kill-input	    	    ^u
+;; c-c c-w backward-kill-word    	    ^w
+;; c-c c-c comint-interrupt-subjob 	    ^c
+;; c-c c-z comint-stop-subjob	    	    ^z
+;; c-c c-\ comint-quit-subjob	    	    ^\
+;; c-c c-o comint-kill-output		    Delete last batch of process output
+;; c-c c-r comint-show-output		    Show last batch of process output
+;;         send-invisible                  Read line w/o echo & send to proc
+;;         comint-continue-subjob	    Useful if you accidentally suspend
+;;					        top-level job.
+;; comint-mode-hook is the comint mode hook.
+
+;; CMU Lisp Mode Commands:
+;; c-m-x   lisp-send-defun     This binding is a gnu convention.
+;; c-c c-l lisp-load-file  	Prompt for file name; tell Lisp to load it.
+;; c-c c-k lisp-compile-file	Prompt for file name; tell Lisp to kompile it.
+;; 	    	    	    	Filename completion is available, of course.
+;;
+;; Additionally, these commands are added to the key bindings of Lisp mode:
+;; c-m-x   lisp-eval-defun         This binding is a gnu convention.
+;; c-c c-e lisp-eval-defun 	    Send the current defun to Lisp process.
+;; c-x c-e lisp-eval-last-sexp     Send the previous sexp to Lisp process.
+;; c-c c-r lisp-eval-region        Send the current region to Lisp process.
+;; c-c c-c lisp-compile-defun      Compile the current defun in Lisp process.
+;; c-c c-z switch-to-lisp          Switch to the Lisp process buffer.
+;; c-c c-l lisp-load-file          (See above. In a Lisp file buffer, default
+;; c-c c-k lisp-compile-file        is to load/compile the current file.)
+;; c-c c-d lisp-describe-sym	    Query Lisp for a symbol's description.
+;; c-c c-a lisp-show-arglist	    Query Lisp for function's arglist.
+;; c-c c-f lisp-show-function-documentation Query Lisp for a function's doc.
+;; c-c c-v lisp-show-variable-documentation Query Lisp for a variable's doc.
+
+;; cmulisp	    	    	    Fires up the Lisp process.
+;; lisp-compile-region     	    Compile all forms in the current region.
+;;
+;; CMU Lisp Mode Variables:
+;; cmulisp-filter-regexp	    Match this => don't get saved on input hist
+;; inferior-lisp-program   	    Name of Lisp program run-lisp executes
+;; inferior-lisp-load-command	    Customises lisp-load-file
+;; cmulisp-mode-hook  	    
+;; inferior-lisp-prompt	    Initialises comint-prompt-regexp.
+;;				    Backwards compatibility.
+;; lisp-source-modes               Anything loaded into a buffer that's in
+;;                                 one of these modes is considered Lisp 
+;;                                 source by lisp-load/compile-file.
+
+;;; Code:
+
+(require 'comint)
 
 ;;; Read the rest of this file for more information.
 

lisp/cmuscheme.el

 ;;; cmuscheme.el --- Scheme process in a buffer. Adapted from tea.el.
 
-;;; Copyright (C) 1988 Free Software Foundation, Inc.
+
+;; Copyright (C) 1988 Free Software Foundation, Inc.
 
 ;; Author: Olin Shivers <olin.shivers@cs.cmu.edu>
 ;; Keywords: processes, lisp

lisp/comint.el

 ;;; comint.el --- general command interpreter in a window stuff
+
 ;; Copyright (C) 1988, 1990, 1992, 1993 Free Software Foundation, Inc.
 
 ;; Author: Olin Shivers <shivers@cs.cmu.edu>

lisp/compare-w.el

@@ -20,6 +20,13 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; This package provides one entry point, compare-windows.  It compares
+;; text starting from point in two adjacent windows, advancing point
+;; until it finds a difference.  Option variables permit you to ignore
+;; whitespace differences, or case differences, or both.
+
 ;;; Code:
 
 (defvar compare-windows-whitespace " \t\n"

lisp/diff.el

@@ -20,6 +20,12 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; This package helps you explore differences between files, using the
+;; UNIX command diff(1).  The commands are `diff' and `diff-backup'.
+;; You can specify options with `diff-switches'.
+
 ;;; Code:
 
 (require 'compile)

lisp/dired-aux.el

@@ -22,6 +22,10 @@
 
 ;;; Commentary:
 
+;; The parts of dired mode not normally used.  This is a space-saving hack
+;; to avoid having to load a large mode when all that's wanted are a few
+;; functions.
+
 ;; Rewritten in 1990/1991 to add tree features, file marking and
 ;; sorting by Sebastian Kremer <sk@thp.uni-koeln.de>.
 ;; Finished up by rms in 1992.

lisp/dired.el

@@ -23,6 +23,9 @@
 
 ;;; Commentary:
 
+;; This is a major mode for directory browsing and editing.  It is
+;; documented in the Emacs manual.
+
 ;; Rewritten in 1990/1991 to add tree features, file marking and
 ;; sorting by Sebastian Kremer <sk@thp.uni-koeln.de>.
 ;; Finished up by rms in 1992.

lisp/ebuff-menu.el

@@ -22,8 +22,9 @@
 
 ;;; Commentary:
 
-;; who says one can't have typeout windows in gnu emacs?
-;; like ^r select buffer from its emacs lunar or tmacs libraries.
+;; Who says one can't have typeout windows in GNU Emacs?   The entry
+;; point, `electric-buffer-list' works like ^r select buffer from the
+;; ITS Emacs lunar or tmacs libraries.
 
 ;;; Code:
 

lisp/ehelp.el

@@ -21,6 +21,14 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; This package provides a pre-packaged `Electric Help Mode' for
+;; browsing on-line help screens.  There is one entry point,
+;; `with-electric-help'; All you have to give it is a no-argument
+;; function that generates the actual text of the help into the urrent
+;; buffer.
+
 ;;; Code:
 
 (require 'electric)

lisp/emacs-lisp/autoload.el

@@ -21,6 +21,13 @@
 ;;; 02139, USA.
 ;;;
 
+;;; Commentary;:
+
+;; This code helps GNU Emacs maintainers keep the autoload.el file up to
+;; date.  It interprets magic cookies of the form ";;;###autoload" in
+;; lisp source files in various useful ways.  To learn more, read the
+;; source; if you're going to use this, you'd better be able to.
+
 ;;; Code:
 
 (defun make-autoload (form file)

lisp/emacs-lisp/bytecomp.el

@@ -28,6 +28,12 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; The Emacs Lisp byte compiler.  This crunches lisp source into a sort
+;; of p-code which takes up less space and can be interpreted faster.
+;; The user entry points are byte-compile-file and byte-recompile-directory.
+
 ;;; Code:
 
 ;;; ========================================================================

lisp/emacs-lisp/cl-indent.el

 ;;; cl-indent.el --- enhanced lisp-indent mode
 
 ;; Copyright (C) 1987 Free Software Foundation, Inc.
-;; Written by Richard Mlynarik July 1987
+
 ;; Author: Richard Mlynark <mly@eddie.mit.edu>
+;; Created: July 1987
 ;; Maintainer: FSF
 ;; Keywords: lisp, tools
 
-
 ;; This file is part of GNU Emacs.
 
 ;; GNU Emacs is free software; you can redistribute it and/or modify
@@ -25,6 +25,12 @@
 
 ;;; Commentary:
 
+;; This package supplies a single entry point, common-lisp-indent-function,
+;; which performs indentation in the preferred style for Common Lisp code.
+;; To enable it:
+;;
+;; (setq lisp-indent-function 'common-lisp-indent-function)
+
 ;;>> TODO
 ;; :foo
 ;;   bar
@@ -41,8 +47,6 @@
 
 ;;; Code:
 
-;;; Hairy lisp indentation.
-
 (defvar lisp-indent-maximum-backtracking 3
   "*Maximum depth to backtrack out from a sublist for structured indentation.
 If this variable is  0, no backtracking will occur and forms such as flet
@@ -466,10 +470,4 @@ by `lisp-body-indent'.")
 ;(put 'with-condition-handler 'common-lisp-indent-function '((1 4 ((* 1))) (2 &body)))
 ;(put 'condition-case 'common-lisp-indent-function '((1 4) (* 2 ((0 1) (1 3) (2 &body)))))
 
-
-;;;; Turn it on.
-;(setq lisp-indent-function 'common-lisp-indent-function)
-
-;; To disable this stuff, (setq lisp-indent-function 'lisp-indent-function)
-
 ;;; cl-indent.el ends here

lisp/emacs-lisp/debug.el

@@ -21,6 +21,10 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; This is a major mode documented in the Emacs manual.
+
 ;;; Code:
 
 (defvar debug-function-list nil

lisp/emacs-lisp/disass.el

@@ -25,9 +25,14 @@
 
 ;;; Commentary:
 
-;;; Original version by Doug Cutting (doug@csli.stanford.edu)
-;;; Substantially modified by Jamie Zawinski <jwz@lucid.com> for
-;;; the new lapcode-based byte compiler.
+;; The single entry point, `disassemble', disassembles a code object generated
+;; by the Emacs Lisp byte-compiler.  This doesn't invert the compilation
+;; operation, not by a long shot, but it's useful for debugging.
+
+;;
+;; Original version by Doug Cutting (doug@csli.stanford.edu)
+;; Substantially modified by Jamie Zawinski <jwz@lucid.com> for
+;; the new lapcode-based byte compiler.
 
 ;;; Code: