Added or corrected Commentary sections

8 files changed, 68 insertions, 37 deletions

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