Added or corrected Commentary sections

64 files changed, 521 insertions, 270 deletions

diff --git a/lisp/abbrev.el b/lisp/abbrev.el
index 3e24f0f6388..39323b938b4 100644
--- a/lisp/abbrev.el
+++ b/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 "\
diff --git a/lisp/ada.el b/lisp/ada.el
index 6cb305c3425..8ee750fc6c0 100644
--- a/lisp/ada.el
+++ b/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))
diff --git a/lisp/add-log.el b/lisp/add-log.el
index ab7760c9c21..7b3b6d26c67 100644
--- a/lisp/add-log.el
+++ b/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
diff --git a/lisp/array.el b/lisp/array.el
index 1c86c11a6b3..c17aae26f4a 100644
--- a/lisp/array.el
+++ b/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:
diff --git a/lisp/autoinsert.el b/lisp/autoinsert.el
index 1046aa65904..9851ded2cdb 100644
--- a/lisp/autoinsert.el
+++ b/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:
 
diff --git a/lisp/buff-menu.el b/lisp/buff-menu.el
index 3e509b5198f..6e70146086e 100644
--- a/lisp/buff-menu.el
+++ b/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
diff --git a/lisp/cmulisp.el b/lisp/cmulisp.el
index b247d79718b..3557be394b5 100644
--- a/lisp/cmulisp.el
+++ b/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.
 
diff --git a/lisp/cmuscheme.el b/lisp/cmuscheme.el
index 6000d421212..982a0c3dc10 100644
--- a/lisp/cmuscheme.el
+++ b/lisp/cmuscheme.el
@@ -1,6 +1,7 @@
 ;;; 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
diff --git a/lisp/comint.el b/lisp/comint.el
index 80abf0cd752..bc737c8a20d 100644
--- a/lisp/comint.el
+++ b/lisp/comint.el
@@ -1,4 +1,5 @@
 ;;; 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>
diff --git a/lisp/compare-w.el b/lisp/compare-w.el
index d4d6a4d746e..b7df1ad31b4 100644
--- a/lisp/compare-w.el
+++ b/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"
diff --git a/lisp/diff.el b/lisp/diff.el
index cd85ec29d10..bb33689c0f9 100644
--- a/lisp/diff.el
+++ b/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)
diff --git a/lisp/dired-aux.el b/lisp/dired-aux.el
index 0af40a03c54..3cff0fc3ea7 100644
--- a/lisp/dired-aux.el
+++ b/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.
diff --git a/lisp/dired.el b/lisp/dired.el
index e68b58891ec..859f8e108ba 100644
--- a/lisp/dired.el
+++ b/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.
diff --git a/lisp/ebuff-menu.el b/lisp/ebuff-menu.el
index 3e92bfdb387..eedc984df06 100644
--- a/lisp/ebuff-menu.el
+++ b/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:
 
diff --git a/lisp/ehelp.el b/lisp/ehelp.el
index e73fe74a124..baa2a052181 100644
--- a/lisp/ehelp.el
+++ b/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)
diff --git a/lisp/emacs-lisp/autoload.el b/lisp/emacs-lisp/autoload.el
index 257aaed9769..2b02f1f1e41 100644
--- a/lisp/emacs-lisp/autoload.el
+++ b/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)
diff --git a/lisp/emacs-lisp/bytecomp.el b/lisp/emacs-lisp/bytecomp.el
index 921737df870..ab40f109e93 100644
--- a/lisp/emacs-lisp/bytecomp.el
+++ b/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:
 
 ;;; ========================================================================
diff --git a/lisp/emacs-lisp/cl-indent.el b/lisp/emacs-lisp/cl-indent.el
index 537b16e6916..f063f92ee7a 100644
--- a/lisp/emacs-lisp/cl-indent.el
+++ b/lisp/emacs-lisp/cl-indent.el
@@ -1,12 +1,12 @@
 ;;; 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
diff --git a/lisp/emacs-lisp/debug.el b/lisp/emacs-lisp/debug.el
index c37250f8eae..910a5ddf322 100644
--- a/lisp/emacs-lisp/debug.el
+++ b/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
diff --git a/lisp/emacs-lisp/disass.el b/lisp/emacs-lisp/disass.el
index 9045032cad0..b60ba5a2385 100644
--- a/lisp/emacs-lisp/disass.el
+++ b/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:
 
diff --git a/lisp/emacs-lisp/edebug.el b/lisp/emacs-lisp/edebug.el
index e5a366f6880..61961f68251 100644
--- a/lisp/emacs-lisp/edebug.el
+++ b/lisp/emacs-lisp/edebug.el
@@ -5,6 +5,10 @@
 ;; Author: Daniel LaLiberte <liberte@cs.uiuc.edu>
 ;; Keywords: lisp, tools, maint
 
+;; This is Dan's 2.5 version with some header comments rearranged to separate
+;; the Change Log from the Commentary (so the package-finder code can browse
+;; the Commentary).
+
 ;; This file is part of GNU Emacs.
 
 ;; GNU Emacs is distributed in the hope that it will be useful,
@@ -41,17 +45,30 @@
 
 ;;; Contents:
 ;;; =========
-;;; Change list
 ;;; Installation
-;;; Todo list
+;;; Change list
 ;;; Utilities
 ;;; Parser
 ;;; Debugger
 
 
-;;;================================================================
-;;; Change list
-;;; -----------
+;;; Installation
+;;; ------------
+;; Put edebug.el in some directory in your load-path and byte-compile it.
+
+;; Put the following forms in your .emacs file.
+;; (define-key emacs-lisp-mode-map "\^Xx" 'edebug-defun)
+;; (autoload 'edebug-defun "edebug")
+;; (autoload 'edebug-debug "edebug")
+;; (setq debugger 'edebug-debug)
+;; ... other options, described in the next section.
+
+;; Evaluate a defun for edebug with edebug-defun.  
+;; Evaluate your function normally.
+;; Use the "?" command in edebug to describe other commands.
+;; See edebug.texinfo for more instructions.
+
+;;; Change Log:
 
 ;;; Revision 2.5  91/07/25  13:32:53  liberte
 ;;; Doc string cleanup.
@@ -171,23 +188,6 @@
 ;;; Initial revision
 ;;; 
 
-
-;;; Installation
-;;; ------------
-;; Put edebug.el in some directory in your load-path and byte-compile it.
-
-;; Put the following forms in your .emacs file.
-;; (define-key emacs-lisp-mode-map "\^Xx" 'edebug-defun)
-;; (autoload 'edebug-defun "edebug")
-;; (autoload 'edebug-debug "edebug")
-;; (setq debugger 'edebug-debug)
-;; ... other options, described in the next section.
-
-;; Evaluate a defun for edebug with edebug-defun.  
-;; Evaluate your function normally.
-;; Use the "?" command in edebug to describe other commands.
-;; See edebug.texinfo for more instructions.
-
 ;;; Code:
 
 
diff --git a/lisp/emacs-lisp/lisp-mode.el b/lisp/emacs-lisp/lisp-mode.el
index f56fefedf00..67c2a96c069 100644
--- a/lisp/emacs-lisp/lisp-mode.el
+++ b/lisp/emacs-lisp/lisp-mode.el
@@ -23,6 +23,13 @@
 
 ;;; Code:
 
+;;; Commentary:
+
+;; The base major mode for editing Lisp code (used also for Emacs Lisp).
+;; This mode is documented in the Emacs manual
+
+;;; Code:
+
 (defvar lisp-mode-syntax-table nil "")
 (defvar emacs-lisp-mode-syntax-table nil "")
 (defvar lisp-mode-abbrev-table nil "")
@@ -94,8 +101,8 @@
   (setq comment-start-skip ";+ *")
   (make-local-variable 'comment-column)
   (setq comment-column 40)
-  (make-local-variable 'comment-indent-hook)
-  (setq comment-indent-hook 'lisp-comment-indent))
+  (make-local-variable 'comment-indent-function)
+  (setq comment-indent-function 'lisp-comment-indent))
 
 (defvar shared-lisp-mode-map ()
   "Keymap for commands shared by all sorts of Lisp modes.")
diff --git a/lisp/emacs-lisp/lisp.el b/lisp/emacs-lisp/lisp.el
index c35574b73be..9cd00517cc2 100644
--- a/lisp/emacs-lisp/lisp.el
+++ b/lisp/emacs-lisp/lisp.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:
+
+;; Lisp ediing commands to go with Lisp major mode.
+
 ;;; Code:
 
 (defvar defun-prompt-regexp nil
diff --git a/lisp/emerge.el b/lisp/emerge.el
index 09c29fbb680..c0efed32175 100644
--- a/lisp/emerge.el
+++ b/lisp/emerge.el
@@ -1,4 +1,5 @@
 ;;; emerge.el --- merge diffs under Emacs control
+
 ;;; The author has placed this file in the public domain.
 
 ;; Author: Dale R. Worley <drw@math.mit.edu>
@@ -7,120 +8,8 @@
 
 ;;; Commentary:
 
-; - Changes from version 3 to version 4
-; 
-; More configuration variables are marked as user options.
-; 
-; Code is included for an improved version of make-auto-save-file-name
-; which eliminates many problems with the default version.  See the
-; documentation of emerge-make-auto-save-file-name to see how to
-; activate it.
-; 
-; Emerge now works with Gnu diff3, which can produce the groups of lines
-; from the various files in the order 1, 2, 3 or 1, 3, 2.
-; 
-; Added x f command to show what files or buffers are being operated on.
-; 
-; The merge buffer now starts read-only, which being in fast mode it
-; should be.
-; 
-; When merging buffers, Emerge writes their contents into temporary
-; files in the directory $TMPDIR (if it is defined), or /tmp by default.
-; 
-; Added x j command to join two differences.
-; 
-; Added x s command to split a difference into two differences.
-; 
-; Added emerge-version variable and function to report the version of Emerge
-; being run.
-; 
-; Added x t command to trim unchanged lines off top and bottom of
-; difference region.
-; 
-; Added x d, x a, and x b commands to locate the differences at or near
-; a given location in one of the buffers.
-; 
-; Emerge no longer tries to copy the minor modes from the A buffer to
-; the merge buffer, only the major mode.
-; 
-; The programs executed to find the differences between versions of the file
-; are no longer controlled by emerge-diff/diff3-command, but rather by:
-;   emerge-diff-program	      
-;     Variable: *Name of the program which compares two files.
-;   emerge-diff3-program	      
-;     Variable: *Name of the program which compares an ancestor file
-;     (first argument) and two variant files (second and third arguments).
-;   emerge-diff-options	      
-;     Variable: *Options to be passed to emerge-diff/diff3-program.
-; 
-; The names of the files are expanded (see expand-file-name) before being
-; passed to emerge-diff/diff3-program, so diff need not invoked under a shell
-; that understands '~', for instance.
-; 
-; If the diff/diff3 program reports errors, the user is notified and the
-; errors are displayed.
-; 
-; The command "0j" can be used to suppress the flags from showing in the buffers.
-; 
-; A discussion of the effect of the merge flags on indentation of code
-; has been added to the documentation.
-; 
-; If kill-fix.el is loaded, Emerge control variables new have their
-; 'preserved' property set, so setting the major mode in the merge
-; buffer doesn't destroy Emerge's state.
-; 
-; Added x c, x C, and x x commands to allow the A and B versions to be
-; combined into #ifdef - #endif forms.
-; 
-; Replaced calls of "ding" to calls of "error" where appropriate.
-; 
-; Added x m command to allow major mode of merge buffer to be changed.
-; 
-; Added x 1 command to shrink the merge window to one line.
-; 
-; Added emerge-startup-hook to allow customization.
-; 
-; Fixed a bug that is activated when a remote merge request is made when
-; the minibuffer window is selected.
-; 
-; - Changes from version 2 to version 3
-; 
-; The directory into which temporary files are written is now controlled
-; by a user option (emerge-temp-file-prefix).
-; 
-; The A and B versions of the difference can be loaded into the kill
-; ring with the "c a" and "c b" commands.
-; 
-; The A and B versions of the difference can be inserted into the merge
-; buffer with the "i a" and "i b" commands.
-; 
-; The difference region of the merge buffer can be surrounded by the
-; point and mark with the "m" command.
-; 
-; The three windows can be scrolled together with the "^", "v", "<",
-; ">", and "|" commands.
-; 
-; The "s s" and "s a" commands report the state of the option in the
-; echo area.  Similarly, the "f" and "e" commands report what they do in
-; the echo area.
-; 
-; The "q" command has been revamped, and its behavior is now controlled
-; by the manner in which Emerge is started.  In particular, if you wish
-; to write the merge buffer into a file upon exiting, invoke
-; emerge-files[-with-ancestor] with a prefix argument, and it will
-; prompt you for the file name.  Then exiting will write the merge
-; buffer to the file, unless "q" is given a prefix argument.
-; 
-; The "i a" and "i b" commands now work in fast mode.
-; 
-; The modifications that Emerge makes to save-buffer and write-file are
-; described.
-; 
-; Emerge now handles merging narrowed buffers correctly.
-; 
-; Emerge now isn't fooled when the buffer visiting a file is not the
-; same as the file on disk.
-; 
+;; This package assists you in reconciling differences between pair of files.
+
 ; - Starting
 ; 
 ; To start Emerge, you must run one of four commands:
@@ -558,6 +447,122 @@
 ; 
 ; ================================================================
 
+;;; Change Log:
+
+; - Changes from version 3 to version 4
+; 
+; More configuration variables are marked as user options.
+; 
+; Code is included for an improved version of make-auto-save-file-name
+; which eliminates many problems with the default version.  See the
+; documentation of emerge-make-auto-save-file-name to see how to
+; activate it.
+; 
+; Emerge now works with Gnu diff3, which can produce the groups of lines
+; from the various files in the order 1, 2, 3 or 1, 3, 2.
+; 
+; Added x f command to show what files or buffers are being operated on.
+; 
+; The merge buffer now starts read-only, which being in fast mode it
+; should be.
+; 
+; When merging buffers, Emerge writes their contents into temporary
+; files in the directory $TMPDIR (if it is defined), or /tmp by default.
+; 
+; Added x j command to join two differences.
+; 
+; Added x s command to split a difference into two differences.
+; 
+; Added emerge-version variable and function to report the version of Emerge
+; being run.
+; 
+; Added x t command to trim unchanged lines off top and bottom of
+; difference region.
+; 
+; Added x d, x a, and x b commands to locate the differences at or near
+; a given location in one of the buffers.
+; 
+; Emerge no longer tries to copy the minor modes from the A buffer to
+; the merge buffer, only the major mode.
+; 
+; The programs executed to find the differences between versions of the file
+; are no longer controlled by emerge-diff/diff3-command, but rather by:
+;   emerge-diff-program	      
+;     Variable: *Name of the program which compares two files.
+;   emerge-diff3-program	      
+;     Variable: *Name of the program which compares an ancestor file
+;     (first argument) and two variant files (second and third arguments).
+;   emerge-diff-options	      
+;     Variable: *Options to be passed to emerge-diff/diff3-program.
+; 
+; The names of the files are expanded (see expand-file-name) before being
+; passed to emerge-diff/diff3-program, so diff need not invoked under a shell
+; that understands '~', for instance.
+; 
+; If the diff/diff3 program reports errors, the user is notified and the
+; errors are displayed.
+; 
+; The command "0j" can be used to suppress the flags from showing in the buffers.
+; 
+; A discussion of the effect of the merge flags on indentation of code
+; has been added to the documentation.
+; 
+; If kill-fix.el is loaded, Emerge control variables new have their
+; 'preserved' property set, so setting the major mode in the merge
+; buffer doesn't destroy Emerge's state.
+; 
+; Added x c, x C, and x x commands to allow the A and B versions to be
+; combined into #ifdef - #endif forms.
+; 
+; Replaced calls of "ding" to calls of "error" where appropriate.
+; 
+; Added x m command to allow major mode of merge buffer to be changed.
+; 
+; Added x 1 command to shrink the merge window to one line.
+; 
+; Added emerge-startup-hook to allow customization.
+; 
+; Fixed a bug that is activated when a remote merge request is made when
+; the minibuffer window is selected.
+; 
+; - Changes from version 2 to version 3
+; 
+; The directory into which temporary files are written is now controlled
+; by a user option (emerge-temp-file-prefix).
+; 
+; The A and B versions of the difference can be loaded into the kill
+; ring with the "c a" and "c b" commands.
+; 
+; The A and B versions of the difference can be inserted into the merge
+; buffer with the "i a" and "i b" commands.
+; 
+; The difference region of the merge buffer can be surrounded by the
+; point and mark with the "m" command.
+; 
+; The three windows can be scrolled together with the "^", "v", "<",
+; ">", and "|" commands.
+; 
+; The "s s" and "s a" commands report the state of the option in the
+; echo area.  Similarly, the "f" and "e" commands report what they do in
+; the echo area.
+; 
+; The "q" command has been revamped, and its behavior is now controlled
+; by the manner in which Emerge is started.  In particular, if you wish
+; to write the merge buffer into a file upon exiting, invoke
+; emerge-files[-with-ancestor] with a prefix argument, and it will
+; prompt you for the file name.  Then exiting will write the merge
+; buffer to the file, unless "q" is given a prefix argument.
+; 
+; The "i a" and "i b" commands now work in fast mode.
+; 
+; The modifications that Emerge makes to save-buffer and write-file are
+; described.
+; 
+; Emerge now handles merging narrowed buffers correctly.
+; 
+; Emerge now isn't fooled when the buffer visiting a file is not the
+; same as the file on disk.
+
 ;;; Code:
 
 ;;; Macros
diff --git a/lisp/files.el b/lisp/files.el
index 88150a7133b..f27ceff0506 100644
--- a/lisp/files.el
+++ b/lisp/files.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:
+
+;; Defines most of Emacs's file- and directory-handling functions,
+;; including basic file visiting, backup generation, link handling,
+;; ITS-id version control, load- and write-hook handling, and the like.
+
 ;;; Code:
 
 (defconst delete-auto-save-files t
diff --git a/lisp/gosmacs.el b/lisp/gosmacs.el
index c432f4293cf..93bbbaa5b80 100644
--- a/lisp/gosmacs.el
+++ b/lisp/gosmacs.el
@@ -21,6 +21,11 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; Make GNU Emacs look like Gosling Emacs.  `M-x set-gosmacs-bindings'
+;; does this change; `M-x set-gnu-bindings' undoes it.
+
 ;;; Code:
 
 (require 'mlsupport)
diff --git a/lisp/hexl.el b/lisp/hexl.el
index a38e12366ee..20e9c161754 100644
--- a/lisp/hexl.el
+++ b/lisp/hexl.el
@@ -22,6 +22,12 @@
 
 ;;; Commentary:
 
+;; This package implements a major mode for editing binary files.  It uses
+;; a program called hexl, supplied with the GNU Emacs distribution, that
+;; can filter a binary into an editable format or from the format back into
+;; binary.  For full instructions, invoke `hexl-mode' on an empty buffer and
+;; do `M-x describe-mode'.
+;;
 ;; This may be useful in your .emacs:
 ;;
 ;;	(autoload 'hexl-find-file "hexl"
@@ -74,7 +80,7 @@ and \"-de\" when dehexlfying a buffer.")
 ;;;###autoload
 (defun hexl-mode (&optional arg)
   "\\<hexl-mode-map>
-A major mode for editting binary files in hex dump format.
+A major mode for editing binary files in hex dump format.
 
 This function automatically converts a buffer into the hexl format
 using the function `hexlify-buffer'.
diff --git a/lisp/indent.el b/lisp/indent.el
index 8a972b82349..dd6a0588453 100644
--- a/lisp/indent.el
+++ b/lisp/indent.el
@@ -20,6 +20,11 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; Commands for making and changing indentation in text.  These are
+;; described in the Emacs manual.
+
 ;;; Code:
 
 (defvar indent-line-function 'indent-to-left-margin "\
diff --git a/lisp/international/iso-insert.el b/lisp/international/iso-insert.el
index efe7e0cd3c7..89528d0bc60 100644
--- a/lisp/international/iso-insert.el
+++ b/lisp/international/iso-insert.el
@@ -22,10 +22,12 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
-;;; Code:
+;;; Commentary:
 
 ;; Written by Howard Gayle.  See case-table.el for details.
 
+;;; Code:
+
 (defun insert-no-break-space ()
    (interactive "*")
    (insert 160)
diff --git a/lisp/international/iso-swed.el b/lisp/international/iso-swed.el
index a39c70c3706..107d2f6c4dc 100644
--- a/lisp/international/iso-swed.el
+++ b/lisp/international/iso-swed.el
@@ -22,10 +22,12 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
-;;; Code:
+;;; Commentary:
 
 ;; Written by Howard Gayle.  See case-table.el for details.
 
+;;; Code:
+
 ;; This code sets up to display ISO 8859/1 characters on
 ;; terminals that have ASCII in the G0 set and a Swedish/Finnish
 ;; version of ISO 646 in the G1 set.  The G1 set differs from
diff --git a/lisp/iso8859-1.el b/lisp/iso8859-1.el
index 7cca9047704..1f6c23a9ddc 100644
--- a/lisp/iso8859-1.el
+++ b/lisp/iso8859-1.el
@@ -22,10 +22,12 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
-;;; Code:
+;;; Commentary:
 
 ;; Written by Howard Gayle.  See case-table.el for details.
 
+;;; Code:
+
 (require 'case-table)
 
 (let ((table (standard-case-table)))
diff --git a/lisp/kermit.el b/lisp/kermit.el
index 66f9c18414a..9387c098372 100644
--- a/lisp/kermit.el
+++ b/lisp/kermit.el
@@ -4,6 +4,7 @@
 
 ;; Author: Jeff Norden <jeff@colgate.csnet>
 ;; Created: 15 Feb 1988
+;; Keywords: comm
 
 ;; This file is part of GNU Emacs.
 
@@ -21,7 +22,7 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
-;;; Commentary
+;;; Commentary:
 
 ;; I'm not sure, but I think somebody asked about running kermit under shell
 ;; mode a while ago.  Anyway, here is some code that I find useful.  The result
@@ -51,8 +52,8 @@
 ;; ^C^Q^C to send an interrupt, and ^C^Q^Z for a stop signal, etc.  (since ^C^C
 ;; just generates a local stop signal, which kermit ignores).
 ;; To connect to a VMS system, I use a shell script to invoke kermit thru the
-;; tr filter, do "M-X kermit-send-cr", and then tell VMS that I'm on a half-duplex
-;; terminal.
+;; tr filter, do "M-X kermit-send-cr", and then tell VMS that I'm on a 
+;; half-duplex terminal.
 
 ;; Some caveats:
 ;; 1) Kermit under shell mode is a real pain if you don't have pty's.  I
diff --git a/lisp/ledit.el b/lisp/ledit.el
index fa7892545cf..f76aa468d89 100644
--- a/lisp/ledit.el
+++ b/lisp/ledit.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 for editing Liszt.  See etc/LEDIT for details.
+
 ;;; Code:
 
 ;;; To do:
diff --git a/lisp/lpr.el b/lisp/lpr.el
index 1f4ec62dfc1..2beead551ec 100644
--- a/lisp/lpr.el
+++ b/lisp/lpr.el
@@ -21,6 +21,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:
+
+;; Commands to send the region or a buffer your printer.  Entry points
+;; are `lpr-buffer', `print-buffer', lpr-region', or `print-region'; option
+;; variables include `lpr-switches' and `lpr-command'.
+
 ;;; Code:
 
 ;;;###autoload
diff --git a/lisp/macros.el b/lisp/macros.el
index f1aec4e51b8..41c021897cd 100644
--- a/lisp/macros.el
+++ b/lisp/macros.el
@@ -21,6 +21,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:
+
+;; Extension commands for keyboard macros.  These permit you to assign
+;; a name to the last-defined keyboard macro, expand and insert the
+;; lisp corresponding to a macro, query the user from within a macro,
+;; or apply a macro to each line in the reason.
+
 ;;; Code:
 
 ;;;###autoload
diff --git a/lisp/mail/emacsbug.el b/lisp/mail/emacsbug.el
index 3af19d75ab3..8f64f8f8da7 100644
--- a/lisp/mail/emacsbug.el
+++ b/lisp/mail/emacsbug.el
@@ -23,6 +23,11 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; `M-x report-emacs-bug ' starts an email note to the Emacs maintainers
+;; describing a problem.  Here's how it's done...
+
 ;;; Code:
 
 ;; >> This should be an address which is accessible to your machine,
diff --git a/lisp/mail/mail-utils.el b/lisp/mail/mail-utils.el
index d165dc6d756..63757511013 100644
--- a/lisp/mail/mail-utils.el
+++ b/lisp/mail/mail-utils.el
@@ -21,6 +21,11 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; Utility functions for maol and netnews handling.  These handle fine
+;; points of header parsing.
+
 ;;; Code:
 
 ;;; We require lisp-mode to make sure that lisp-mode-syntax-table has
diff --git a/lisp/mail/mailalias.el b/lisp/mail/mailalias.el
index b07725a5a7c..3918a520e04 100644
--- a/lisp/mail/mailalias.el
+++ b/lisp/mail/mailalias.el
@@ -21,6 +21,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:
+
+;; Basic functions for defining and expanding mail aliases.
+;; These seal off the interface to the alias-definition parts of a
+;; .mailrc file formatted for BSD's Mail or USL's mailx.
+
 ;;; Code:
 
 (defvar mail-aliases t
diff --git a/lisp/makesum.el b/lisp/makesum.el
index 0808501f4ee..a9311e0906e 100644
--- a/lisp/makesum.el
+++ b/lisp/makesum.el
@@ -21,6 +21,11 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; Displays a nice human-readable summary of all keybindings in a
+;; two-column format.
+
 ;;; Code:
 
 ;;;###autoload
diff --git a/lisp/mim-mode.el b/lisp/mim-mode.el
index 25d60d947ef..b5970de19ea 100644
--- a/lisp/mim-mode.el
+++ b/lisp/mim-mode.el
@@ -225,8 +225,8 @@ Entry to this mode calls the value of mim-mode-hook if non-nil."
   (setq comment-end "\"")
   (make-local-variable 'comment-column)
   (setq comment-column 40)
-  (make-local-variable 'comment-indent-hook)
-  (setq comment-indent-hook 'indent-mim-comment)
+  (make-local-variable 'comment-indent-function)
+  (setq comment-indent-function 'indent-mim-comment)
   ;; tell generic indenter how to indent.
   (make-local-variable 'indent-line-function)
   (setq indent-line-function 'indent-mim-line)
diff --git a/lisp/play/dissociate.el b/lisp/play/dissociate.el
index d399212a441..ebf6b637a8d 100644
--- a/lisp/play/dissociate.el
+++ b/lisp/play/dissociate.el
@@ -21,6 +21,11 @@
 ;; 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 single entry point, `dissociatesd-press', applies a travesty
+;; generator to the current buffer.  The results can be quite amusing.
+
 ;;; Code:
 
 ;;;###autoload
diff --git a/lisp/play/doctor.el b/lisp/play/doctor.el
index 315c4cc11f7..702f053b25e 100644
--- a/lisp/play/doctor.el
+++ b/lisp/play/doctor.el
@@ -21,6 +21,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 single entry point `doctor', simulates a Rogerian analyst using
+;; phrase-production techniques similar to the classic ELIZA demonstration
+;; of pseudo-AI.
+
 ;;; Code:
 
 (defun doctor-cadr (x) (car (cdr x)))
diff --git a/lisp/play/hanoi.el b/lisp/play/hanoi.el
index e65608235fd..99e2acdd92a 100644
--- a/lisp/play/hanoi.el
+++ b/lisp/play/hanoi.el
@@ -8,6 +8,35 @@
 ; This is in the public domain
 ; since he distributed it without copyright notice in 1985.
 
+;;; Commentary:
+
+;; Solves the Towers of Hanoi puzzle while-U-wait.
+;;
+;; The puzzle: Start with N rings, decreasing in sizes from bottom to
+;; top, stacked around a post.  There are two other posts.  Your mission,
+;; should you choose to accept it, is to shift the pile, stacked in its
+;; original order, to another post.
+;;
+;; The challenge is to do it in the fewest possible moves.  Each move
+;; shifts one ring to a different post.  But there's a rule; you can
+;; only stack a ring on top of a larger one.
+;;
+;; The simplest nontrivial version of this puzzle is N = 3.  Solution
+;; time rises as 2**N, and programs to solve it have long been considered
+;; classic introductory exercises in the use of recursion.
+;;
+;; The puzzle is called `Towers of Hanoi' because an early popular
+;; presentation wove a fanciful legend around it.  According to this
+;; myth (uttered long before the Vietnam War), there is a Buddhist
+;; monastery at Hanoi which contains a large room with three time-worn
+;; posts in it surrounded by 21 golden discs.  Monks, acting out the
+;; command of an ancient prophecy, have been moving these disks, in
+;; accordance with the rules of the puzzle, once every day since the
+;; monastery was founded over a thousand years ago.  They are said
+;; believe that when the last move of the puzzle is completed, the
+;; world will end in a clap of thunder.  Fortunately, they are nowhere
+;; even close to being done...
+
 ;;; Code:
 
 ;;;
diff --git a/lisp/play/life.el b/lisp/play/life.el
index 8b8c34b4b98..8e1732ed303 100644
--- a/lisp/play/life.el
+++ b/lisp/play/life.el
@@ -21,6 +21,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:
+
+;; A demonstrator for John Horton Conway's "Life" cellular automaton
+;; in Emacs Lisp.  Picks a random one of a set of interesting Life
+;; patterns and avolves it according to the familiar rules.
+
 ;;; Code:
 
 (defconst life-patterns
diff --git a/lisp/progmodes/awk-mode.el b/lisp/progmodes/awk-mode.el
index b4ec8ddfb0e..40300e9bc22 100644
--- a/lisp/progmodes/awk-mode.el
+++ b/lisp/progmodes/awk-mode.el
@@ -21,6 +21,11 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; Sets up C-mode with support for awk-style #-comments and a lightly
+;; hacked syntax table.
+
 ;;; Code:
 
 (defvar awk-mode-syntax-table nil
@@ -83,8 +88,8 @@ with no args, if that value is non-nil."
   (setq comment-column 32)
   (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)
   (run-hooks 'awk-mode-hook))
 
 ;;; awk-mode.el ends here
diff --git a/lisp/progmodes/c-mode.el b/lisp/progmodes/c-mode.el
index 957db277012..a9f7e0cedef 100644
--- a/lisp/progmodes/c-mode.el
+++ b/lisp/progmodes/c-mode.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:
+
+;; A smart editing mode for C code.  It knows a lot about C syntax and tries
+;; to position the curser according to C layout conventions.  You can
+;; change the details of the layout style with option variables.  Load it
+;; and do M-x describe-mode for details.
+
 ;;; Code:
 
 (defvar c-mode-abbrev-table nil
@@ -204,8 +211,8 @@ if that value is non-nil."
   (setq comment-column 32)
   (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 'c-mode-hook))
diff --git a/lisp/progmodes/cmacexp.el b/lisp/progmodes/cmacexp.el
index 144ac7ab56f..dd2c6df2c67 100644
--- a/lisp/progmodes/cmacexp.el
+++ b/lisp/progmodes/cmacexp.el
@@ -1,4 +1,4 @@
-;;; cmacexp.el --- C macro expansion
+;;; cmacexp.el --- C preprocessor macro expansion
 
 ;; Copyright (C) 1988 Free Software Foundation, Inc.
 
@@ -21,6 +21,18 @@
 ;; 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 gives you the ability to run the C macro preprocessor
+;; on the current region, expanding macros within it.  This can be useful
+;; when you're not sure of the value or expansion of such macros and want
+;; to make sure they're doing what you think they're doing.
+;;
+;; This package supports the following option variables:
+;;
+;; c-macro-preprocessor --- program to be used for macro expansion.
+;; c-macro-options --- command-line options to pass it.
+
 ;;; Code:
 
 (defvar c-macro-preprocessor "/lib/cpp"
diff --git a/lisp/progmodes/compile.el b/lisp/progmodes/compile.el
index cacea5194ee..eeee97c7231 100644
--- a/lisp/progmodes/compile.el
+++ b/lisp/progmodes/compile.el
@@ -5,6 +5,7 @@
 ;; Author: Roland McGrath <roland@prep.ai.mit.edu>
 ;; Maintainer: FSF
 ;; Keywords: tools, processes
+;; Info-Node: Emacs:Compilation
 
 ;; This file is part of GNU Emacs.
 
diff --git a/lisp/progmodes/cplus-md.el b/lisp/progmodes/cplus-md.el
index 45b325d6850..5689183a56a 100644
--- a/lisp/progmodes/cplus-md.el
+++ b/lisp/progmodes/cplus-md.el
@@ -21,9 +21,10 @@
 
 ;;; Commentary:
 
-;; 1987 Dave Detlefs  (dld@cs.cmu.edu) 
-;; and  Stewart Clamen (clamen@cs.cmu.edu).
+;; 1987 Dave Detlefs  <dld@cs.cmu.edu> 
+;; and  Stewart Clamen <clamen@cs.cmu.edu>.
 ;; Done by fairly faithful modification of:
+
 ;;; Change Log:
 
 ;; Feb, 1990 (Dave Detlefs, dld@cs.cmu.edu)
@@ -219,7 +220,7 @@ no args if that value is non-nil."
   (set (make-local-variable 'comment-start) "// ")
   (set (make-local-variable 'comment-end) "")
   (set (make-local-variable 'comment-start-skip) "/\\*+ *\\|// *")
-  (set (make-local-variable 'comment-indent-hook) 'c++-comment-indent)
+  (set (make-local-variable 'comment-indent-function) 'c++-comment-indent)
   (set (make-local-variable 'paragraph-start) (concat "^$\\|" page-delimiter))
   (set (make-local-variable 'paragraph-separate) paragraph-start)
   (set (make-local-variable 'paragraph-ignore-fill-prefix) t)
diff --git a/lisp/progmodes/fortran.el b/lisp/progmodes/fortran.el
index e4035940726..7f9aa77d9b4 100644
--- a/lisp/progmodes/fortran.el
+++ b/lisp/progmodes/fortran.el
@@ -354,8 +354,8 @@ with no args, if that value is non-nil."
   (setq fortran-break-before-delimiters t)
   (make-local-variable 'indent-line-function)
   (setq indent-line-function 'fortran-indent-line)
-  (make-local-variable 'comment-indent-hook)
-  (setq comment-indent-hook 'fortran-comment-hook)
+  (make-local-variable 'comment-indent-function)
+  (setq comment-indent-function 'fortran-comment-hook)
   (make-local-variable 'comment-line-start-skip)
   (setq comment-line-start-skip
 	"^[Cc*]\\(\\([^ \t\n]\\)\\2\\2*\\)?[ \t]*\\|^#.*")
@@ -475,7 +475,6 @@ Any other key combination is executed normally."
   "List the currently defined abbrevs in Fortran mode."
   (interactive)
   (message "Listing abbrev table...")
-  (require 'abbrevlist)
   (display-buffer (fortran-prepare-abbrev-list-buffer))
   (message "Listing abbrev table...done"))
 
diff --git a/lisp/progmodes/hideif.el b/lisp/progmodes/hideif.el
index efd866fb89f..4d8ecefe7bf 100644
--- a/lisp/progmodes/hideif.el
+++ b/lisp/progmodes/hideif.el
@@ -23,15 +23,6 @@
 
 ;;; Commentary:
 
-;;; Written by Brian Marick, at Gould, Computer Systems Division, Urbana IL.
-;;; Extensively modified by Daniel LaLiberte (while at Gould).
-;;;
-;;; You may freely modify and distribute this, but keep a record
-;;; of modifications and send comments to:
-;;; 	 liberte@a.cs.uiuc.edu  or  ihnp4!uiucdcs!liberte
-;;; I will continue to upgrade hide-ifdef-mode
-;;; with your contributions.
-
 ;;; To initialize, toggle the hide-ifdef minor mode with
 ;;;
 ;;; M-x hide-ifdef-mode
@@ -105,6 +96,15 @@
 ;;; If you have minor-mode-alist in your mode line (the default) two labels
 ;;; may appear.  "Ifdef" will appear when hide-ifdef-mode is active.  "Hiding"
 ;;; will appear when text may be hidden ("hide-ifdef-hiding" is non-nil).
+;;;
+;;; Written by Brian Marick, at Gould, Computer Systems Division, Urbana IL.
+;;; Extensively modified by Daniel LaLiberte (while at Gould).
+;;;
+;;; You may freely modify and distribute this, but keep a record
+;;; of modifications and send comments to:
+;;; 	 liberte@a.cs.uiuc.edu  or  ihnp4!uiucdcs!liberte
+;;; I will continue to upgrade hide-ifdef-mode
+;;; with your contributions.
 
 ;;; Change Log:
 ;;;
diff --git a/lisp/progmodes/icon.el b/lisp/progmodes/icon.el
index 2a2f5a9dcd4..f64ed19dd37 100644
--- a/lisp/progmodes/icon.el
+++ b/lisp/progmodes/icon.el
@@ -24,6 +24,8 @@
 
 ;;; Commentary:
 
+;; A major mode for editing the Icon programming language.
+;;
 ;; Note: use
 ;;  (autoload 'icon-mode "icon" nil t)
 ;;  (setq auto-mode-alist (cons '("\\.icn$" . icon-mode) auto-mode-alist))
@@ -146,8 +148,8 @@ with no args, if that value is non-nil."
   (setq comment-column 32)
   (make-local-variable 'comment-start-skip)
   (setq comment-start-skip "# *")
-  (make-local-variable 'comment-indent-hook)
-  (setq comment-indent-hook 'icon-comment-indent)
+  (make-local-variable 'comment-indent-function)
+  (setq comment-indent-function 'icon-comment-indent)
   (run-hooks 'icon-mode-hook))
 
 ;; This is used by indent-for-comment to decide how much to
diff --git a/lisp/progmodes/make-mode.el b/lisp/progmodes/make-mode.el
index b8e19e48e19..4dcc45cee12 100644
--- a/lisp/progmodes/make-mode.el
+++ b/lisp/progmodes/make-mode.el
@@ -6,7 +6,7 @@
 ;; Adapted-By: ESR
 ;; Keywords: unix, tools
 
-;; $Id: makefile.el,v 1.7.1.17 1992/07/15 20:05:15 tom Exp tom $
+;; $Id: makefile.el,v 1.3 1992/07/22 02:13:37 eric Exp eric $
 
 ;; This file is part of GNU Emacs.
 
@@ -24,6 +24,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:
+
+;; A major mode for editing Makefiles.  Hairy.  Needs more documentation.
+;; If you get familiar with it, please write some and send it to the GNU
+;; Emacs maintainers.
+
 ;;; Code:
 
 (provide 'makefile)
diff --git a/lisp/progmodes/modula2.el b/lisp/progmodes/modula2.el
index 2a84787c8d6..fd261980d80 100644
--- a/lisp/progmodes/modula2.el
+++ b/lisp/progmodes/modula2.el
@@ -134,8 +134,8 @@ followed by the first character of the construct.
   (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 'm2-mode-hook))
diff --git a/lisp/progmodes/perl-mode.el b/lisp/progmodes/perl-mode.el
index 0f0599bafe8..5afd03adc74 100644
--- a/lisp/progmodes/perl-mode.el
+++ b/lisp/progmodes/perl-mode.el
@@ -243,8 +243,8 @@ args, if that value is non-nil."
   (setq comment-column 32)
   (make-local-variable 'comment-start-skip)
   (setq comment-start-skip "\\(^\\|\\s-\\);?#+ *")
-  (make-local-variable 'comment-indent-hook)
-  (setq comment-indent-hook 'perl-comment-indent)
+  (make-local-variable 'comment-indent-function)
+  (setq comment-indent-function 'perl-comment-indent)
   (make-local-variable 'parse-sexp-ignore-comments)
   (setq parse-sexp-ignore-comments nil)
   (run-hooks 'perl-mode-hook))
diff --git a/lisp/progmodes/prolog.el b/lisp/progmodes/prolog.el
index 35472d9d587..d6b93b70a42 100644
--- a/lisp/progmodes/prolog.el
+++ b/lisp/progmodes/prolog.el
@@ -77,8 +77,8 @@ nil means send actual operating system end of file.")
   (setq comment-start-skip "%+ *")
   (make-local-variable 'comment-column)
   (setq comment-column 48)
-  (make-local-variable 'comment-indent-hook)
-  (setq comment-indent-hook 'prolog-comment-indent))
+  (make-local-variable 'comment-indent-function)
+  (setq comment-indent-function 'prolog-comment-indent))
 
 (defun prolog-mode-commands (map)
   (define-key map "\t" 'prolog-indent-line)
diff --git a/lisp/progmodes/scheme.el b/lisp/progmodes/scheme.el
index 3a470f9fa49..76190c948b4 100644
--- a/lisp/progmodes/scheme.el
+++ b/lisp/progmodes/scheme.el
@@ -104,8 +104,8 @@
   (setq comment-start-skip ";+[ \t]*")
   (make-local-variable 'comment-column)
   (setq comment-column 40)
-  (make-local-variable 'comment-indent-hook)
-  (setq comment-indent-hook 'scheme-comment-indent)
+  (make-local-variable 'comment-indent-function)
+  (setq comment-indent-function 'scheme-comment-indent)
   (setq mode-line-process '("" scheme-mode-line-process)))
 
 (defvar scheme-mode-line-process "")
diff --git a/lisp/textmodes/bib-mode.el b/lisp/textmodes/bib-mode.el
index 5a9bd6e0e6f..d772ddcff1e 100644
--- a/lisp/textmodes/bib-mode.el
+++ b/lisp/textmodes/bib-mode.el
@@ -21,14 +21,15 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
-;;; Code:
+;;; Commentary:
 
-;; Bib-Mode
 ;;   GNU Emacs code to help maintain databases compatible with (troff)
 ;;   refer and lookbib.  The file bib-file should be set to your 
 ;;   bibliography file.  Keys are automagically inserted as you type,
 ;;   and appropriate keys are presented for various kinds of entries.
 
+;;; Code:
+
 (defvar bib-file "~/my-bibliography.bib" 
    "Default name of file used by `addbib'.")
 
diff --git a/lisp/textmodes/bibtex.el b/lisp/textmodes/bibtex.el
index 851bf9f64d9..b441eaa9fbd 100644
--- a/lisp/textmodes/bibtex.el
+++ b/lisp/textmodes/bibtex.el
@@ -25,6 +25,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:
+
+;; A major mode for entering and editing BibTex files, validating
+;; them, canonicalizing them, and sorting them.  Includes entry
+;; commands tailored to many different formats (book, master's this,
+;; journal article, etc).  Has loads of options.
+
 ;;; Change Log:
 
 ;;; alarson@src.honeywell.com 92-Jan-31
diff --git a/lisp/textmodes/fill.el b/lisp/textmodes/fill.el
index eb2ba5be696..a905bef78d1 100644
--- a/lisp/textmodes/fill.el
+++ b/lisp/textmodes/fill.el
@@ -20,6 +20,11 @@
 ;; along with GNU Emacs; see the file COPYING.  If not, write to
 ;; the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
 
+;;; Commentary:
+
+;; All the commands for filling text.  These are documented in the Emacs
+;; manual.
+
 ;;; Code:
 
 (defconst fill-individual-varying-indent nil
diff --git a/lisp/textmodes/ispell4.el b/lisp/textmodes/ispell4.el
index ded85446595..4520ebcff0d 100644
--- a/lisp/textmodes/ispell4.el
+++ b/lisp/textmodes/ispell4.el
@@ -20,6 +20,11 @@
 ;;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 graceful interface to ispell, the GNU
+;; spelling checker.
+
 ;;; Code:
 
 (defvar ispell-have-new-look t
diff --git a/lisp/textmodes/nroff-mode.el b/lisp/textmodes/nroff-mode.el
index bc2013412de..5c87ca567ff 100644
--- a/lisp/textmodes/nroff-mode.el
+++ b/lisp/textmodes/nroff-mode.el
@@ -67,8 +67,8 @@ closing requests for requests that are used in matched pairs."
   (setq comment-start-skip "\\\\\"[ \t]*")
   (make-local-variable 'comment-column)
   (setq comment-column 24)
-  (make-local-variable 'comment-indent-hook)
-  (setq comment-indent-hook 'nroff-comment-indent)
+  (make-local-variable 'comment-indent-function)
+  (setq comment-indent-function 'nroff-comment-indent)
   (run-hooks 'text-mode-hook 'nroff-mode-hook))
 
 ;;; Compute how much to indent a comment in nroff/troff source.
diff --git a/lisp/textmodes/sgml-mode.el b/lisp/textmodes/sgml-mode.el
index d03e631a91e..b6200ac0bc7 100644
--- a/lisp/textmodes/sgml-mode.el
+++ b/lisp/textmodes/sgml-mode.el
@@ -89,8 +89,8 @@ Use \\[sgml-validate] to validate your document with an SGML parser."
   (setq comment-start "<!-- ")
   (make-local-variable 'comment-end)
   (setq comment-end " -->")
-  (make-local-variable 'comment-indent-hook)
-  (setq comment-indent-hook 'sgml-comment-indent)
+  (make-local-variable 'comment-indent-function)
+  (setq comment-indent-function 'sgml-comment-indent)
   (make-local-variable 'comment-start-skip)
   ;; This will allow existing comments within declarations to be
   ;; recognized.
diff --git a/lisp/textmodes/tex-mode.el b/lisp/textmodes/tex-mode.el
index cee97ffa407..7835bfd120a 100644
--- a/lisp/textmodes/tex-mode.el
+++ b/lisp/textmodes/tex-mode.el
@@ -437,8 +437,8 @@ tex-shell-hook is called."
   (setq comment-start "%")
   (make-local-variable 'comment-start-skip)
   (setq comment-start-skip "\\(\\(^\\|[^\\]\\)\\(\\\\\\\\\\)*\\)\\(%+ *\\)")
-  (make-local-variable 'comment-indent-hook)
-  (setq comment-indent-hook 'tex-comment-indent)
+  (make-local-variable 'comment-indent-function)
+  (setq comment-indent-function 'tex-comment-indent)
   (make-local-variable 'compare-windows-whitespace)
   (setq compare-windows-whitespace 'tex-categorize-whitespace)
   (make-local-variable 'tex-command)