Added or corrected Commentary sections

16 files changed, 101 insertions, 1 deletions

diff --git a/lisp/emulation/mlconvert.el b/lisp/emulation/mlconvert.el
index 20b51466e4f..c186622e43b 100644
--- a/lisp/emulation/mlconvert.el
+++ b/lisp/emulation/mlconvert.el
@@ -3,7 +3,7 @@
 ;; Copyright (C) 1985 Free Software Foundation, Inc.
 
 ;; Maintainer: FSF
-;; Keywords: extensions
+;; Keywords: emulations
 
 ;; This file is part of GNU Emacs.
 
@@ -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:
+
+;; This package conversts Mocklisp code written under a Gosling or UniPress
+;; Emacs for use with GNU Emacs.  The translated code will require runtime
+;; support from the mlsupport.el equivalent.
+
 ;;; Code:
 
 ;;;###autoload
diff --git a/lisp/emulation/mlsupport.el b/lisp/emulation/mlsupport.el
index c5091b70434..63576d52f8b 100644
--- a/lisp/emulation/mlsupport.el
+++ b/lisp/emulation/mlsupport.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 equivalents of certain primitives from Gosling
+;; Emacs (including the commercial UniPress versions).  These have an
+;; ml- prefix to distinguish them from native GNU Emacs functions with
+;; similar names.  The oackage mlconvert.el translates Mocklisp code
+;; to use these names.
+
 ;;; Code:
 
 (defmacro ml-defun (&rest defs)
diff --git a/lisp/man.el b/lisp/man.el
index 1f367fc7a6e..6461f3f2447 100644
--- a/lisp/man.el
+++ b/lisp/man.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:
+
+;; This package provides an equivalent of the UNIX man(1) command within
+;; Emacs.  The single entry point is `manual-entry'.
+
 ;;; Code:
 
 ;;;###autoload
diff --git a/lisp/mouse.el b/lisp/mouse.el
index aca35b30994..0b3a1824f94 100644
--- a/lisp/mouse.el
+++ b/lisp/mouse.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 various useful commands (including help
+;; system access) through the mouse.  All this code assumes that mouse
+;; interpretation has been abstracted into Emacs input events.
+;;
+;; The code is rather X-dependent.
+
 ;;; Code:
 
 ;;; Utility functions.
diff --git a/lisp/netunam.el b/lisp/netunam.el
index 21fb36afc03..492ac9b2c12 100644
--- a/lisp/netunam.el
+++ b/lisp/netunam.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:
+
+;; Use the Remote File Access (RFA) facility of HP-UX from Emacs.
+
 ;;; Code:
 
 (defconst rfa-node-directory "/net/"
diff --git a/lisp/novice.el b/lisp/novice.el
index 1590a104861..2ddbbac3250 100644
--- a/lisp/novice.el
+++ b/lisp/novice.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:
+
+;; This mode provides a hook which is, by default, attached to various
+;; putatively dangerous commands in a (probably futile) attempt to
+;; prevent lusers from shooting themselves in the feet.
+
 ;;; Code:
 
 ;; This function is called (by autoloading)
diff --git a/lisp/options.el b/lisp/options.el
index 0b831a5ad5a..ca78256b562 100644
--- a/lisp/options.el
+++ b/lisp/options.el
@@ -20,6 +20,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 code provides functions to list and edit the values of all global
+;; option variables known to loaded Emacs Lisp code.  There are two entry
+;; points, `list-options' and `edit' options'.  The latter enters a major
+;; mode specifically for editing option values.  Do `M-x describe-mode' in
+;; that context for more details.
+
 ;;; Code:
 
 ;;;###autoload
diff --git a/lisp/play/mpuz.el b/lisp/play/mpuz.el
index 28811924470..4cdb252be0c 100644
--- a/lisp/play/mpuz.el
+++ b/lisp/play/mpuz.el
@@ -22,6 +22,13 @@
 ;; file named COPYING.  Among other things, the copyright notice
 ;; and this notice must be preserved on all copies.
 
+;;; Commentary:
+
+;; When this package is loaded, `M-x mpuz' generates a random multiplication
+;; puzzle.  This is a multiplication example in which each digit has been
+;; consistently replaced with some letter.  Your job is to reconstruct
+;; the original digits.  Type `?' while the mode is active for detailed help.
+
 ;;; Code:
 
 (random t)                              ; randomize
diff --git a/lisp/progmodes/modula2.el b/lisp/progmodes/modula2.el
index fd261980d80..21b7d475b30 100644
--- a/lisp/progmodes/modula2.el
+++ b/lisp/progmodes/modula2.el
@@ -11,6 +11,12 @@
 ;; Author Mick Jordan
 ;; amended Peter Robinson
 
+;;; Commentary:
+
+;; A major mode for editing Modula-2 code.  It provides convenient abbrevs
+;; for Modula-2 keywords, knows about the standard layout rules, and supports
+;; a native compile command.
+
 ;;; Code:
 
 ;;; Added by Tom Perrine (TEP)
diff --git a/lisp/progmodes/prolog.el b/lisp/progmodes/prolog.el
index d6b93b70a42..52b65113073 100644
--- a/lisp/progmodes/prolog.el
+++ b/lisp/progmodes/prolog.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:
+
+;; This package provides a major mode for editing Prolog.  It knows
+;; about Prolog syntax and comments, and can send regions to an inferior
+;; Prolog interpreter process.
+
 ;;; Code:
 
 (defvar prolog-mode-syntax-table nil)
diff --git a/lisp/rect.el b/lisp/rect.el
index 6c2ae12817a..e440904912f 100644
--- a/lisp/rect.el
+++ b/lisp/rect.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:
+
+;; This package provides the operations on rectangles that are ocumented
+;; in the Emacs manual.
+
 ;;; Code:
 
 (defun operate-on-rectangle (function start end coerce-tabs)
diff --git a/lisp/textmodes/nroff-mode.el b/lisp/textmodes/nroff-mode.el
index 5c87ca567ff..273e8ee201b 100644
--- a/lisp/textmodes/nroff-mode.el
+++ b/lisp/textmodes/nroff-mode.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 is a major mode for editing nroff source code.  It knows
+;; about various nroff constructs, ms, mm, and me macros, and will fill
+;; and indent paragraphs properly in their presence.  It also includes
+;; a command to count text lines (excluding nroff constructs), a command
+;; to center a line, and movement commands that know how to skip macros.
+
 ;;; Code:
 
 (defvar nroff-mode-abbrev-table nil
diff --git a/lisp/textmodes/ooutline.el b/lisp/textmodes/ooutline.el
index 1712f4b5682..19ee1f70b29 100644
--- a/lisp/textmodes/ooutline.el
+++ b/lisp/textmodes/ooutline.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 is a major mode for editing outline-format documents.
+;; An outline can be `abstracted' to show headers at any given level,
+;; with all stuff below hidden.  See the Emacs manual for details.
+
 ;;; Code:
 
 ;; Jan '86, Some new features added by Peter Desnoyers and rewritten by RMS.
diff --git a/lisp/textmodes/page.el b/lisp/textmodes/page.el
index 9d57cb18ecf..fca4d9f6608 100644
--- a/lisp/textmodes/page.el
+++ b/lisp/textmodes/page.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 code provides the page-oriented movement and selection commands
+;; documented in the Emacs manual.
+
 ;;; Code:
 
 (defun forward-page (&optional count)
diff --git a/lisp/textmodes/paragraphs.el b/lisp/textmodes/paragraphs.el
index e404a995cf7..baebf2d23ff 100644
--- a/lisp/textmodes/paragraphs.el
+++ b/lisp/textmodes/paragraphs.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:
+
+;; This package provides the paragraph-oriented commands documented in the
+;; Emacs manual.
+
 ;;; Code:
 
 (defconst paragraph-start "^[ \t\n\f]" "\
diff --git a/lisp/textmodes/picture.el b/lisp/textmodes/picture.el
index 622269bec1b..a0864a79c0f 100644
--- a/lisp/textmodes/picture.el
+++ b/lisp/textmodes/picture.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:
+
+;; This code provides the picture-mode commands documented in the Emacs 
+;; manual.  The screen is treated as a semi-infinite quarter-plane with
+;; support for rectangle operations and `etch-a-sketch' character
+;; insertion in any of eight directions.
+
 ;;; Code:
 
 (defun move-to-column-force (column)