[Emacs-diffs] Changes to emacs/lisp/calc/calc.el,v

[Jay Belanger]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Jay Belanger <jpb>      08/03/23 02:25:34

Index: calc.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/calc/calc.el,v
retrieving revision 1.104
retrieving revision 1.105
diff -u -b -r1.104 -r1.105
--- calc.el     20 Mar 2008 03:07:01 -0000      1.104
+++ calc.el     23 Mar 2008 02:25:33 -0000      1.105
@@ -507,7 +507,7 @@
       (calc-mode-var-list-restore-default-values))))
 
 (defcalcmodevar calc-always-load-extensions nil
-  "If non-nil, load the calc-ext module automatically when calc is loaded.")
+  "If non-nil, load the calc-ext module automatically when Calc is loaded.")
 
 (defcalcmodevar  calc-line-numbering t
   "If non-nil, display line numbers in Calculator stack.")
@@ -738,27 +738,39 @@
 (defcalcmodevar calc-autorange-units nil
   "If non-nil, automatically set unit prefixes to keep units in a reasonable 
range.")
 
-(defcalcmodevar calc-was-keypad-mode nil)
+(defcalcmodevar calc-was-keypad-mode nil
+  "Non-nil if Calc was last invoked in keypad mode.")
 
-(defcalcmodevar calc-full-mode nil)
+(defcalcmodevar calc-full-mode nil
+  "Non-nil if Calc was last invoked in full-screen mode.")
 
-(defcalcmodevar calc-user-parse-tables nil)
+(defcalcmodevar calc-user-parse-tables nil
+  "Alist of languages with user-defined parse rules.")
 
-(defcalcmodevar calc-gnuplot-default-device "default")
+(defcalcmodevar calc-gnuplot-default-device "default"
+  "The default device name for GNUPLOT plotting.")
 
-(defcalcmodevar calc-gnuplot-default-output "STDOUT")
+(defcalcmodevar calc-gnuplot-default-output "STDOUT"
+  "The default output file for GNUPLOT plotting.")
 
-(defcalcmodevar calc-gnuplot-print-device "postscript")
+(defcalcmodevar calc-gnuplot-print-device "postscript"
+  "The default device name for GNUPLOT printing.")
 
-(defcalcmodevar calc-gnuplot-print-output "auto")
+(defcalcmodevar calc-gnuplot-print-output "auto"
+  "The default output for GNUPLOT printing.")
 
-(defcalcmodevar calc-gnuplot-geometry nil)
+(defcalcmodevar calc-gnuplot-geometry nil
+  "The default geometry for the GNUPLOT window.")
 
-(defcalcmodevar calc-graph-default-resolution 15)
+(defcalcmodevar calc-graph-default-resolution 15
+  "The default number of data points when plotting curves.")
 
-(defcalcmodevar calc-graph-default-resolution-3d 5)
+(defcalcmodevar calc-graph-default-resolution-3d 5
+  "The default number of x- and y- data points when plotting surfaces.")
 
-(defcalcmodevar calc-invocation-macro nil)
+(defcalcmodevar calc-invocation-macro nil
+  "A user defined macro for starting Calc.
+Used by `calc-user-invocation'.")
 
 (defcalcmodevar calc-show-banner t
   "*If non-nil, show a friendly greeting above the stack.")
@@ -892,13 +904,20 @@
 (put 'math-underflow 'error-message "Floating-point underflow occurred")
 
 (defconst calc-version "2.1")
-(defvar calc-trail-pointer nil)                ; "Current" entry in trail 
buffer.
-(defvar calc-trail-overlay nil)                ; Value of overlay-arrow-string.
-(defvar calc-undo-list nil)            ; List of previous operations for undo.
-(defvar calc-redo-list nil)            ; List of recent undo operations.
-(defvar calc-main-buffer nil)          ; Pointer to Calculator buffer.
-(defvar calc-trail-buffer nil)         ; Pointer to Calc Trail buffer.
-(defvar calc-why nil)                  ; Explanations of most recent errors.
+(defvar calc-trail-pointer nil
+  "The \"current\" entry in trail buffer.")
+(defvar calc-trail-overlay nil
+  "The value of overlay-arrow-string.")
+(defvar calc-undo-list nil
+  "The list of previous operations for undo.")
+(defvar calc-redo-list nil
+  "The list of recent undo operations.")
+(defvar calc-main-buffer nil
+  "A pointer to Calculator buffer.")
+(defvar calc-trail-buffer nil
+  "A pointer to Calc Trail buffer.")
+(defvar calc-why nil
+  "Explanations of most recent errors.")
 (defvar calc-next-why nil)
 (defvar calc-inverse-flag nil
   "If non-nil, next operation is Inverse.")
@@ -929,28 +948,46 @@
 (defvar calc-lang-parens-are-subscripts nil
   "Languages in which subscripts are indicated by parentheses.")
 
-(defvar calc-last-kill nil)            ; Last number killed in calc-mode.
-(defvar calc-dollar-values nil)                ; Values to be used for '$'.
-(defvar calc-dollar-used nil)          ; Highest order of '$' that occurred.
-(defvar calc-hashes-used nil)          ; Highest order of '#' that occurred.
-(defvar calc-quick-prev-results nil)   ; Previous results from Quick Calc.
-(defvar calc-said-hello nil)           ; Has welcome message been said yet?
-(defvar calc-executing-macro nil)      ; Kbd macro executing from "K" key.
-(defvar calc-any-selections nil)       ; Nil means no selections present.
-(defvar calc-help-phase 0)             ; Count of consecutive "?" keystrokes.
-(defvar calc-full-help-flag nil)       ; Executing calc-full-help?
-(defvar calc-refresh-count 0)          ; Count of calc-refresh calls.
-(defvar calc-display-dirty nil)
+(defvar calc-last-kill nil
+  "The last number killed in calc-mode.")
+(defvar calc-dollar-values nil
+  "Values to be used for '$'.")
+(defvar calc-dollar-used nil
+  "The highest order of '$' that occurred.")
+(defvar calc-hashes-used nil
+  "The highest order of '#' that occurred.")
+(defvar calc-quick-prev-results nil
+  "Previous results from Quick Calc.")
+(defvar calc-said-hello nil
+  "Non-nil if the welcomd message has been displayed.")
+(defvar calc-executing-macro nil
+  "Non-nil if a keyboard macro is executing from the \"K\" key.")
+(defvar calc-any-selections nil
+  "Non-nil if there are selections present.")
+(defvar calc-help-phase 0
+  "The number of consecutive \"?\" keystrokes.")
+(defvar calc-full-help-flag nil
+  "Non-nil if `calc-full-help' is being executed.")
+(defvar calc-refresh-count 0
+  "The number of `calc-refresh' calls.")
+(defvar calc-display-dirty nil
+  "Non-nil if the stack display might not reflect the latest mode settings.")
 (defvar calc-prepared-composition nil)
 (defvar calc-selection-cache-default-entry nil)
-(defvar calc-embedded-info nil)
-(defvar calc-embedded-active nil)
-(defvar calc-standalone-flag nil)
-(defvar var-EvalRules nil)
+(defvar calc-embedded-info nil
+  "If non-nil, a vector consisting of information for embedded mode.")
+(defvar calc-embedded-active nil
+  "Alist of buffers with sorted lists of calc-embedded-infos.")
+(defvar calc-standalone-flag nil
+  "Non-nil if Emacs started with standalone Calc.")
+(defvar var-EvalRules nil
+  "User defined rules that Calc will apply automatically.")
 (defvar math-eval-rules-cache-tag t)
 (defvar math-radix-explicit-format t)
-(defvar math-expr-function-mapping nil)
-(defvar math-expr-variable-mapping nil)
+(defvar math-expr-function-mapping nil
+  "Alist of language specific functions with Calc functions.")
+(defvar math-expr-variable-mapping nil
+  "Alist of language specific variables with Calc variables.")
 (defvar math-read-expr-quotes nil)
 (defvar math-working-step nil)
 (defvar math-working-step-2 nil)
@@ -964,7 +1001,10 @@
 (mapc (lambda (v) (or (boundp v) (set v nil)))
       calc-local-var-list)
 
-(defvar calc-mode-map
+(defvar calc-mode-map nil
+  "The key map for Calc.")
+
+(or calc-mode-map
   (let ((map (make-keymap)))
     (suppress-keymap map t)
     (define-key map "+" 'calc-plus)
@@ -999,9 +1039,12 @@
                  ":\\|!()[]<>{},;=~`\C-k\M-k\C-w\M-w\C-y\C-_"))
     (mapc (lambda (x) (define-key map (char-to-string x) 'calcDigit-start))
          "_0123456789.#@")
-    map))
+      (setq calc-mode-map map)))
+
+(defvar calc-digit-map nil
+  "The key map for entering Calc digits.")
 
-(defvar calc-digit-map
+(or calc-digit-map
   (let ((map (make-keymap)))
     (if (featurep 'xemacs)
        (map-keymap (function
@@ -1025,7 +1068,7 @@
     (define-key map "'" 'calcDigit-algebraic)
     (define-key map "`" 'calcDigit-edit)
     (define-key map "\C-g" 'abort-recursive-edit)
-    map))
+      (setq calc-digit-map map)))
 
 (mapc (lambda (x)
        (condition-case err
@@ -1051,7 +1094,10 @@
                  '("\C-d"))
        '("\177" "\C-d")))
 
-(defvar calc-dispatch-map
+(defvar calc-dispatch-map nil
+  "The key map for starting Calc.")
+
+(or calc-dispatch-map
   (let ((map (make-keymap)))
     (mapc (lambda (x)
            (define-key map (char-to-string (car x)) (cdr x))
@@ -1098,7 +1144,7 @@
            ( ?/ . calc-same-interface )
            ( ?+ . calc-same-interface )
            ( ?- . calc-same-interface ) ))
-    map))
+      (setq calc-dispatch-map map)))
 
 ;;;; (Autoloads here)
 (mapc
@@ -1161,6 +1207,7 @@
 
 (defvar calc-dispatch-help nil)
 (defun calc-do-dispatch (arg)
+  "Start the Calculator."
   (let ((key (calc-read-key-sequence
              (if calc-dispatch-help
                  "Calc options: Calc, Keypad, Quick, Embed; eXit; Info, 
Tutorial; Grab; ?=more"
@@ -1176,6 +1223,7 @@
       (beep))))
 
 (defun calc-read-key-sequence (prompt map)
+  "Read keys, with prompt PROMPT and keymap MAP."
   (let ((prompt2 (format "%s " (key-description (this-command-keys))))
        (glob (current-global-map))
        (loc (current-local-map)))
@@ -1313,6 +1361,7 @@
   (run-mode-hooks 'calc-trail-mode-hook))
 
 (defun calc-create-buffer ()
+  "Create and initialize a buffer for the Calculator."
   (set-buffer (get-buffer-create "*Calculator*"))
   (or (eq major-mode 'calc-mode)
       (calc-mode))
@@ -1396,6 +1445,7 @@
         (calc arg calc-full-mode t)))))
 
 (defun calc-quit (&optional non-fatal interactive)
+  "Quit the Calculator in an appropriate manner."
   (interactive "i\np")
   (and calc-standalone-flag (not non-fatal)
        (save-buffers-kill-emacs nil))