Mercurial > emacs
changeset 105474:0a64442c10e3
Fix typos.
* emacs-lisp/chart.el, emacs-lisp/eieio.el, emacs-lisp/eieio-base.el
* emacs-lisp/eieio-comp.el, emacs-lisp/eieio-custom.el
* emacs-lisp/eieio-datadebug.el, emacs-lisp/eieio-opt.el
* emacs-lisp/eieio-speedbar.el
| author | Juanma Barranquero <lekktu@gmail.com> |
|---|---|
| date | Mon, 05 Oct 2009 15:32:08 +0000 |
| parents | 07f6674a0832 |
| children | dbbce03200d3 |
| files | lisp/ChangeLog lisp/emacs-lisp/chart.el lisp/emacs-lisp/eieio-base.el lisp/emacs-lisp/eieio-comp.el lisp/emacs-lisp/eieio-custom.el lisp/emacs-lisp/eieio-datadebug.el lisp/emacs-lisp/eieio-opt.el lisp/emacs-lisp/eieio-speedbar.el lisp/emacs-lisp/eieio.el |
| diffstat | 9 files changed, 211 insertions(+), 156 deletions(-) [+] |
line wrap: on
line diff
--- a/lisp/ChangeLog Mon Oct 05 15:12:29 2009 +0000 +++ b/lisp/ChangeLog Mon Oct 05 15:32:08 2009 +0000 @@ -1,3 +1,56 @@ +2009-10-05 Juanma Barranquero <lekktu@gmail.com> + + * emacs-lisp/chart.el (chart-face-pixmap-list, chart-new-buffer, chart) + (chart-axis-range, chart-axis-names, chart-sequece, chart-bar) + (chart-draw, chart-axis-draw, chart-sort, chart-sort-matchlist) + (chart-draw-line, chart-bar-quickie): Fix typos in docstrings. + + * emacs-lisp/eieio.el (generic-p, eieiomt-next, eieio-generic-form) + (eieio-default-superclass): Reflow docstrings. + (this, class-option-assoc, defclass, eieio-class-un-autoload) + (eieio-unbind-method-implementations, defmethod) + (eieio-validate-slot-value, eieio-validate-class-slot-value) + (oref-default, eieio-oref-default, eieio-oset, eieio-oset-default) + (with-slots, eieio-add-new-slot, object-assoc, object-remove-from-list) + (eieio-slot-originating-class-p, eieio-slot-name-index) + (eieio-pre-method-execution-hooks, eieio-initarg-to-attribute) + (constructor, initialize-instance, no-next-method, object-print) + (object-write, eieio-override-prin1, eieio-edebug-prin1-to-string): + Fix typos in docstrings. + (eieio-defclass, eieio-perform-slot-validation-for-default, defgeneric) + (child-of-class-p, object-slots, slot-boundp, slot-exists-p) + (next-method-p): Doc fixes. + (eieio-add-new-slot, call-next-method, eieiomt-add, change-class): + Fix typos in error messages. + (eieio-defmethod): Fix typo in description of generic method. + + * emacs-lisp/eieio-base.el (eieio-instance-inheritor, slot-unbound) + (eieio-persistent-save-interactive, slot-missing): + Fix typos in docstrings. + (eieio-instance-inheritor-slot-boundp): Doc fix. + + * emacs-lisp/eieio-comp.el (byte-compile-file-form-defmethod) + (byte-compile-defmethod-param-convert): Fix typos in docstrings. + + * emacs-lisp/eieio-custom.el (eieio-done-customizing) + (eieio-custom-object-apply-reset): + Fix typos in docstrings and error messages. + + * emacs-lisp/eieio-datadebug.el (data-debug-show): + Fix typo in docstring. + + * emacs-lisp/eieio-opt.el (top): Fix typo in error message. + (eieio-browse-tree): Doc fix. + (eieio-all-generic-functions, eieio-class-speedbar): Reflow docstrings. + (eieio-help-mode-augmentation-maybee, eieio-class-speedbar-make-map): + Fix typos in docstrings. + + * emacs-lisp/eieio-speedbar.el (eieio-speedbar-file-button): Doc fix. + (eieio-speedbar-key-map, eieio-speedbar-create-engine) + (eieio-speedbar-buttons, eieio-speedbar, eieio-speedbar-object-children) + (eieio-speedbar-make-tag-line, eieio-speedbar-object-expand): + Reflow docstrings. + 2009-10-05 Dan Nicolaescu <dann@ics.uci.edu> * vc-hg.el (log-view-vc-backend): Declare for compiler. @@ -24,14 +77,13 @@ (tramp-methods): Add recursive option to `tramp-copy-args'. Add `tramp-copy-recursive'. Valid for "rcp", "scp", "scp1", "scp2", "scp1_old", "scp2_old", "rsync", "rsyncc". - (tramp-default-method): Check also for - `auth-source-user-or-password'. + (tramp-default-method): Check also for `auth-source-user-or-password'. (tramp-file-name-handler-alist, tramp-file-name-for-operation): Add handler for `copy-directory'. (tramp-handle-copy-directory): New defun. (tramp-do-copy-or-rename-file-out-of-band): Handle directory case. - (tramp-handle-start-file-process): Raise an error when PROGRAM is - nil. Optimize sent command. + (tramp-handle-start-file-process): Raise an error when PROGRAM is nil. + Optimize sent command. 2009-10-05 Stefan Monnier <monnier@iro.umontreal.ca> @@ -4741,7 +4793,7 @@ blocks. (verilog-init-font) Remove definition & use of verilog-init-font, as it is redundant with font-lock-defaults. - (verilog-mode): Alter the definition of verilog-font-lock-defualts + (verilog-mode): Alter the definition of verilog-font-lock-defaults to avoid circular calls if syntax-ppss is a function (as is the case now in 22.x GNU Emacs) as that function would sometimes call itself, leading to (nearly) infinite recursion.
--- a/lisp/emacs-lisp/chart.el Mon Oct 05 15:12:29 2009 +0000 +++ b/lisp/emacs-lisp/chart.el Mon Oct 05 15:32:08 2009 +0000 @@ -87,7 +87,7 @@ (display-graphic-p)) '("dimple1" "scales" "dot" "cross_weave" "boxes" "dimple3")) "If pixmaps are allowed, display these background pixmaps. -Useful if new Emacs is used on B&W display") +Useful if new Emacs is used on B&W display.") (defcustom chart-face-use-pixmaps nil "*Non-nil to use fancy pixmaps in the background of chart face colors." @@ -133,7 +133,7 @@ (defun chart-new-buffer (obj) "Create a new buffer NAME in which the chart OBJ is displayed. -Returns the newly created buffer" +Returns the newly created buffer." (save-excursion (set-buffer (get-buffer-create (format "*%s*" (oref obj title)))) (chart-mode) @@ -162,7 +162,7 @@ (sequences :initarg :sequences :initform nil) ) - "Superclass for all charts to be displayed in an emacs buffer") + "Superclass for all charts to be displayed in an Emacs buffer.") (defmethod initialize-instance :AFTER ((obj chart) &rest fields) "Initialize the chart OBJ being created with FIELDS. @@ -188,13 +188,13 @@ ((bounds :initarg :bounds :initform '(0.0 . 50.0)) ) - "Class used to display an axis defined by a range of values") + "Class used to display an axis defined by a range of values.") (defclass chart-axis-names (chart-axis) ((items :initarg :items :initform nil) ) - "Class used to display an axis which represents different named items") + "Class used to display an axis which represents different named items.") (defclass chart-sequece () ((data :initarg :data @@ -202,16 +202,16 @@ (name :initarg :name :initform "Data") ) - "Class used for all data in different charts") + "Class used for all data in different charts.") (defclass chart-bar (chart) ((direction :initarg :direction :initform vertical)) - "Subclass for bar charts. (Vertical or horizontal)") + "Subclass for bar charts (vertical or horizontal).") (defmethod chart-draw ((c chart) &optional buff) "Start drawing a chart object C in optional BUFF. -Erases current contents of buffer" +Erases current contents of buffer." (save-excursion (if buff (set-buffer buff)) (erase-buffer) @@ -256,7 +256,7 @@ ) (defmethod chart-axis-draw ((a chart-axis) &optional dir margin zone start end) - "Draw some axis for A in direction DIR at with MARGIN in boundry. + "Draw some axis for A in direction DIR with MARGIN in boundary. ZONE is a zone specification. START and END represent the boundary." (chart-draw-line dir (+ margin (if zone zone 0)) start end) @@ -339,8 +339,8 @@ (defmethod chart-axis-draw ((a chart-axis-names) &optional dir margin zone start end) "Draw axis information based upon A range to be spread along the edge. -Optional argument DIR the direction of the chart. -Optional argument MARGIN , ZONE, START and END specify boundaries of the drawing." +Optional argument DIR is the direction of the chart. +Optional arguments MARGIN, ZONE, START and END specify boundaries of the drawing." (call-next-method) ;; We prefer about 5 spaces between each value (let* ((i 0) @@ -465,7 +465,7 @@ (defmethod chart-sort ((c chart) pred) "Sort the data in chart C using predicate PRED. -See `chart-sort-matchlist' for more details" +See `chart-sort-matchlist' for more details." (let* ((sl (oref c sequences)) (s1 (car sl)) (s2 (car (cdr sl))) @@ -486,9 +486,9 @@ ) (defun chart-sort-matchlist (namelst numlst pred) - "Sort NAMELST and NUMLST (both SEQUENCE objects) based on predicate PRED. + "Sort NAMELST and NUMLST (both sequence objects) based on predicate PRED. PRED should be the equivalent of '<, except it must expect two -cons cells of the form (NAME . NUM). See SORT for more details." +cons cells of the form (NAME . NUM). See `sort' for more details." ;; 1 - create 1 list of cons cells (let ((newlist nil) (alst (oref namelst data)) @@ -557,7 +557,7 @@ (defun chart-draw-line (dir zone start end) "Draw a line using line-drawing characters in direction DIR. -Use column or row ZONE between START and END" +Use column or row ZONE between START and END." (chart-display-label (make-string (- end start) (if (eq dir 'vertical) ?| ?\-)) dir zone start end)) @@ -578,12 +578,12 @@ (defun chart-bar-quickie (dir title namelst nametitle numlst numtitle &optional max sort-pred) - "Wash over the complex eieio stuff and create a nice bar chart. + "Wash over the complex EIEIO stuff and create a nice bar chart. Create it going in direction DIR ['horizontal 'vertical] with TITLE using a name sequence NAMELST labeled NAMETITLE with values NUMLST labeled NUMTITLE. Optional arguments: -Set the charts' max element display to MAX, and sort lists with +Set the chart's max element display to MAX, and sort lists with SORT-PRED if desired." (let ((nc (make-instance chart-bar :title title
--- a/lisp/emacs-lisp/eieio-base.el Mon Oct 05 15:12:29 2009 +0000 +++ b/lisp/emacs-lisp/eieio-base.el Mon Oct 05 15:32:08 2009 +0000 @@ -42,7 +42,7 @@ :type eieio-instance-inheritor-child :documentation "The parent of this instance. -If a slot of this class is reference, and is unbound, then the parent +If a slot of this class is referenced, and is unbound, then the parent is checked for a value.") ) "This special class can enable instance inheritance. @@ -53,7 +53,7 @@ (defmethod slot-unbound ((object eieio-instance-inheritor) class slot-name fn) "If a slot OBJECT in this CLASS is unbound, try to inherit, or throw a signal. -SLOT-NAME, is the offending slot. FN is the function signalling the error." +SLOT-NAME is the offending slot. FN is the function signalling the error." (if (slot-boundp object 'parent-instance) ;; It may not look like it, but this line recurses back into this ;; method if the parent instance's slot is unbound. @@ -85,9 +85,9 @@ (defmethod eieio-instance-inheritor-slot-boundp ((object eieio-instance-inheritor) slot) - "Non-nil if the instance inheritor OBJECT's SLOT is bound. -See `slot-boundp' for for details on binding slots. -The instance inheritor uses unbound slots as a way cascading cloned + "Return non-nil if the instance inheritor OBJECT's SLOT is bound. +See `slot-boundp' for details on binding slots. +The instance inheritor uses unbound slots as a way of cascading cloned slot values, so testing for a slot being bound requires extra steps for this kind of object." (if (slot-boundp object slot) @@ -213,7 +213,7 @@ (defmethod eieio-persistent-save-interactive ((this eieio-persistent) prompt &optional name) - "Perpare to save THIS. Use in an `interactive' statement. + "Prepare to save THIS. Use in an `interactive' statement. Query user for file name with PROMPT if THIS does not yet specify a file. Optional argument NAME specifies a default file name." (unless (slot-boundp this 'file) @@ -308,7 +308,7 @@ slot-name operation &optional new-value) "Called when a on-existant slot is accessed. For variable `eieio-named', provide an imaginary `object-name' slot. -Argument OBJ is the Named object. +Argument OBJ is the named object. Argument SLOT-NAME is the slot that was attempted to be accessed. OPERATION is the type of access, such as `oref' or `oset'. NEW-VALUE is the value that was being set into SLOT if OPERATION were
--- a/lisp/emacs-lisp/eieio-comp.el Mon Oct 05 15:12:29 2009 +0000 +++ b/lisp/emacs-lisp/eieio-comp.el Mon Oct 05 15:32:08 2009 +0000 @@ -52,9 +52,9 @@ (defun byte-compile-file-form-defmethod (form) "Mumble about the method we are compiling. -This function is mostly ripped from `byte-compile-file-form-defun', but -it's been modified to handle the special syntax of the defmethod -command. There should probably be one for defgeneric as well, but +This function is mostly ripped from `byte-compile-file-form-defun', +but it's been modified to handle the special syntax of the `defmethod' +command. There should probably be one for `defgeneric' as well, but that is called but rarely. Argument FORM is the body of the method." (setq form (cdr form)) (let* ((meth (car form)) @@ -125,7 +125,7 @@ nil)) (defun byte-compile-defmethod-param-convert (paramlist) - "Convert method params into the params used by the defmethod thingy. + "Convert method params into the params used by the `defmethod' thingy. Argument PARAMLIST is the parameter list to convert." (let ((argfix nil)) (while paramlist
--- a/lisp/emacs-lisp/eieio-custom.el Mon Oct 05 15:12:29 2009 +0000 +++ b/lisp/emacs-lisp/eieio-custom.el Mon Oct 05 15:32:08 2009 +0000 @@ -90,7 +90,7 @@ (defvar eieio-cog nil "Buffer local variable in object customize buffers for the current group.") - (defvar eieio-custom-ignore-eieio-co nil + (defvar eieio-custom-ignore-eieio-co nil "When true, all customizable slots of the current object are updated. Updates occur regardless of the current customization group.") @@ -227,7 +227,7 @@ (when (and (car fcust) (or (not master-group) (member master-group (car fgroup))) (slot-boundp obj (car slots))) - ;; In this case, this slot has a custom type. Create it's + ;; In this case, this slot has a custom type. Create its ;; children widgets. (let ((type (eieio-filter-slot-type widget (car fcust))) (stuff nil)) @@ -320,9 +320,9 @@ obj)) (defmethod eieio-done-customizing ((obj eieio-default-superclass)) - "When a applying change to a widget, call this method. -This method is called by the default widget-edit commands. User made -commands should also call this method when applying changes. + "When applying change to a widget, call this method. +This method is called by the default widget-edit commands. +User made commands should also call this method when applying changes. Argument OBJ is the object that has been customized." nil) @@ -374,7 +374,7 @@ (defmethod eieio-custom-object-apply-reset ((obj eieio-default-superclass)) "Insert an Apply and Reset button into the object editor. -Argument OBJ os the object being customized." +Argument OBJ is the object being customized." (widget-create 'push-button :notify (lambda (&rest ignore) (widget-apply eieio-wo :value-get) @@ -385,16 +385,16 @@ (widget-create 'push-button :notify (lambda (&rest ignore) ;; I think the act of getting it sets - ;; it's value through the get function. + ;; its value through the get function. (message "Applying Changes...") (widget-apply eieio-wo :value-get) (eieio-done-customizing eieio-co) - (message "Applying Changes...Done.")) + (message "Applying Changes...Done")) "Apply") (widget-insert " ") (widget-create 'push-button :notify (lambda (&rest ignore) - (message "Resetting.") + (message "Resetting") (eieio-customize-object eieio-co eieio-cog)) "Reset") (widget-insert " ")
--- a/lisp/emacs-lisp/eieio-datadebug.el Mon Oct 05 15:12:29 2009 +0000 +++ b/lisp/emacs-lisp/eieio-datadebug.el Mon Oct 05 15:32:08 2009 +0000 @@ -122,7 +122,7 @@ ;; A generic function to run DDEBUG on an object and popup a new buffer. ;; (defmethod data-debug-show ((obj eieio-default-superclass)) - "Run ddebug against any EIEIO object OBJ" + "Run ddebug against any EIEIO object OBJ." (data-debug-new-buffer (format "*%s DDEBUG*" (object-name obj))) (data-debug-insert-object-slots obj "]"))
--- a/lisp/emacs-lisp/eieio-opt.el Mon Oct 05 15:12:29 2009 +0000 +++ b/lisp/emacs-lisp/eieio-opt.el Mon Oct 05 15:32:08 2009 +0000 @@ -51,7 +51,7 @@ )) (defun eieio-browse-tree (this-root prefix ch-prefix) - "Recursively, draws the children of the given class on the screen. + "Recursively draw the children of the given class on the screen. Argument THIS-ROOT is the local root of the tree. Argument PREFIX is the character prefix to use. Argument CH-PREFIX is another character prefix to display." @@ -389,7 +389,8 @@ (defun eieio-all-generic-functions (&optional class) "Return a list of all generic functions. -Optional CLASS argument returns only those functions that contain methods for CLASS." +Optional CLASS argument returns only those functions that contain +methods for CLASS." (let ((l nil) tree (cn (if class (symbol-name class) nil))) (mapatoms (lambda (symbol) @@ -552,7 +553,7 @@ ;;; HELP AUGMENTATION ;; (defun eieio-help-mode-augmentation-maybee (&rest unused) - "For buffers thrown into help mode, augment for eieio. + "For buffers thrown into help mode, augment for EIEIO. Arguments UNUSED are not used." ;; Scan created buttons so far if we are in help mode. (when (eq major-mode 'help-mode) @@ -600,13 +601,13 @@ (eval-when-compile (condition-case nil (require 'speedbar) - (error (message "Error loading speedbar... ignored.")))) + (error (message "Error loading speedbar... ignored")))) (defvar eieio-class-speedbar-key-map nil "Keymap used when working with a project in speedbar.") (defun eieio-class-speedbar-make-map () - "Make a keymap for eieio under speedbar." + "Make a keymap for EIEIO under speedbar." (setq eieio-class-speedbar-key-map (speedbar-make-specialized-keymap)) ;; General viewing stuff @@ -637,8 +638,8 @@ (defun eieio-class-speedbar (dir-or-object depth) "Create buttons in speedbar that represents the current project. -DIR-OR-OBJECT is the object to expand, or nil, and DEPTH is the current -expansion depth." +DIR-OR-OBJECT is the object to expand, or nil, and DEPTH is the +current expansion depth." (when (eq (point-min) (point-max)) ;; This function is only called once, to start the whole deal. ;; Ceate, and expand the default object.
--- a/lisp/emacs-lisp/eieio-speedbar.el Mon Oct 05 15:12:29 2009 +0000 +++ b/lisp/emacs-lisp/eieio-speedbar.el Mon Oct 05 15:32:08 2009 +0000 @@ -113,7 +113,7 @@ map)) (defvar eieio-speedbar-key-map (eieio-speedbar-make-map) - "A Generic object based speedbar display keymap.") + "A generic object based speedbar display keymap.") (defvar eieio-speedbar-menu '([ "Edit Object/Field" speedbar-edit-line t] @@ -150,7 +150,7 @@ (defun eieio-speedbar-create-engine (map-fn map-var menu-var modename fetcher) "Create a speedbar mode for displaying an object hierarchy. Called from `eieio-speedbar-create', or the speedbar load-hook. -MAP-FN, MAP-VAR, MENU-VAR, MODENAME, and FETCHER are the same as +MAP-FN, MAP-VAR, MENU-VAR, MODENAME, and FETCHER are the same as in `eieio-speedbar-create'." ;; make sure the keymap exists (funcall map-fn) @@ -171,7 +171,7 @@ (defun eieio-speedbar-buttons (dir-or-object depth fetcher) "Create buttons for the speedbar display. Start in directory DIR-OR-OBJECT. If it is an object, just display that -objects subelements. +object's subelements. Argument DEPTH specifies how far down we have already been displayed. If it is a directory, use FETCHER to fetch all objects associated with that path." @@ -263,7 +263,7 @@ "State of an object being expanded in speedbar.") ) "Class which provides basic speedbar support for child classes. -Add one of thie child classes to this class to the parent list of a class." +Add one of the child classes to this class to the parent list of a class." :method-invocation-order :depth-first :abstract t) @@ -277,7 +277,7 @@ (defclass eieio-speedbar-file-button (eieio-speedbar) ((buttontype :initform bracket) (buttonface :initform speedbar-file-face)) - "Class providing support for objects which behave like a directory." + "Class providing support for objects which behave like a file." :method-invocation-order :depth-first :abstract t) @@ -287,8 +287,8 @@ (defmethod eieio-speedbar-make-tag-line ((object eieio-speedbar) depth) "Insert a tag line into speedbar at point for OBJECT. -All objects a child of symbol `eieio-speedbar' can be created from this -method. Override this if you need non-traditional tag lines. +All objects a child of symbol `eieio-speedbar' can be created from +this method. Override this if you need non-traditional tag lines. Argument DEPTH is the depth at which the tag line is inserted." (let ((children (eieio-speedbar-object-children object)) (exp (oref object expanded))) @@ -345,8 +345,8 @@ (eieio-speedbar-handle-click token)) (defun eieio-speedbar-object-expand (text token indent) - "Expand object represented by TEXT. TOKEN is the object. -INDENT is the current indentation level." + "Expand object represented by TEXT. +TOKEN is the object. INDENT is the current indentation level." (cond ((string-match "+" text) ;we have to expand this file (speedbar-change-expand-button-char ?-) (oset token expanded t) @@ -412,7 +412,7 @@ ;;; Methods to the eieio-speedbar-* classes which need to be overriden. ;; (defmethod eieio-speedbar-object-children ((object eieio-speedbar)) - "Return a list of children to be displayed in SPEEDBAR. + "Return a list of children to be displayed in speedbar. If the return value is a list of OBJECTs, then those objects are queried for details. If the return list is made of strings, then this object will be queried for the details needed
--- a/lisp/emacs-lisp/eieio.el Mon Oct 05 15:12:29 2009 +0000 +++ b/lisp/emacs-lisp/eieio.el Mon Oct 05 15:32:08 2009 +0000 @@ -52,7 +52,7 @@ (message eieio-version)) (eval-and-compile -;; About the above. EIEIO must process it's own code when it compiles +;; About the above. EIEIO must process its own code when it compiles ;; itself, thus, by eval-and-compiling outselves, we solve the problem. ;; Compatibility @@ -98,7 +98,7 @@ Note: Embedded methods are no longer supported. The variable THIS is still set for CLOS methods for the sake of routines like -`call-next-method'") +`call-next-method'.") (defvar scoped-class nil "This is set to a class when a method is running. @@ -205,8 +205,8 @@ (defmacro generic-p (method) "Return t if symbol METHOD is a generic function. -Only methods have the symbol `eieio-method-obarray' as a property (which -contains a list of all bindings to that method type.)" +Only methods have the symbol `eieio-method-obarray' as a property +\(which contains a list of all bindings to that method type.)" `(and (fboundp ,method) (get ,method 'eieio-method-obarray))) (defun generic-primary-only-p (method) @@ -242,7 +242,8 @@ )) (defmacro class-option-assoc (list option) - "Return from LIST the found OPTION. Nil if it doesn't exist." + "Return from LIST the found OPTION. +Return nil if it doesn't exist." `(car-safe (cdr (memq ,option ,list)))) (defmacro class-option (class option) @@ -272,20 +273,20 @@ only one slot may exist in SUPERCLASS as multiple inheritance is not yet supported. Supported tags are: - :initform - initializing form - :initarg - tag used during initialization - :accessor - tag used to create a function to access this slot - :allocation - specify where the value is stored. - defaults to `:instance', but could also be `:class' - :writer - a function symbol which will `write' an object's slot - :reader - a function symbol which will `read' an object - :type - the type of data allowed in this slot (see `typep') + :initform - Initializing form. + :initarg - Tag used during initialization. + :accessor - Tag used to create a function to access this slot. + :allocation - Specify where the value is stored. + Defaults to `:instance', but could also be `:class'. + :writer - A function symbol which will `write' an object's slot. + :reader - A function symbol which will `read' an object. + :type - The type of data allowed in this slot (see `typep'). :documentation - A string documenting use of this slot. The following are extensions on CLOS: :protection - Specify protection for this slot. - Defaults to `:public'. Also use `:protected', or `:private' + Defaults to `:public'. Also use `:protected', or `:private'. :custom - When customizing an object, the custom :type. Public only. :label - A text string label used for a slot when customizing. :group - Name of a customization group this slot belongs in. @@ -293,14 +294,14 @@ See `eieio-override-prin1' as an example. A class can also have optional options. These options happen in place -of documentation, (including a :documentation tag) in addition to +of documentation (including a :documentation tag), in addition to documentation, or not at all. Supported options are: :documentation - The doc-string used for this class. Options added to EIEIO: - :allow-nil-initform - Non-nil to skip typechecking of initforms if nil. + :allow-nil-initform - Non-nil to skip typechecking of null initforms. :custom-groups - List of custom group names. Organizes slots into reasonable groups for customizations. :abstract - Non-nil to prevent instances of this class. @@ -318,8 +319,8 @@ :default-initargs - Initargs to use when initializing new objects of this class. -Due to the way class options are set up, you can add any tags in you -wish, and reference them using the function `class-option'." +Due to the way class options are set up, you can add any tags you wish, +and reference them using the function `class-option'." ;; We must `eval-and-compile' this so that when we byte compile ;; an eieio program, there is no need to load it ahead of time. ;; It also provides lots of nice debugging errors at compile time. @@ -406,15 +407,15 @@ )))) (defsubst eieio-class-un-autoload (cname) - "If class CNAME is in an autoload state, load it's file." + "If class CNAME is in an autoload state, load its file." (when (eq (car-safe (symbol-function cname)) 'autoload) (load-library (car (cdr (symbol-function cname)))))) (defun eieio-defclass (cname superclasses slots options-and-doc) - "See `defclass' for more information. -Define CNAME as a new subclass of SUPERCLASSES, with SLOTS being the -slots residing in that class definition, and with options or documentation -OPTIONS-AND-DOC as the toplevel documentation for this class." + "Define CNAME as a new subclass of SUPERCLASSES. +SLOTS are the slots residing in that class definition, and options or +documentation OPTIONS-AND-DOC is the toplevel documentation for this class. +See `defclass' for more information." ;; Run our eieio-hook each time, and clear it when we are done. ;; This way people can add hooks safely if they want to modify eieio ;; or add definitions when eieio is loaded or something like that. @@ -434,7 +435,7 @@ (aset newc 0 'defclass) (aset newc class-symbol cname) - ;; If this class already existed, and we are updating it's structure, + ;; If this class already existed, and we are updating its structure, ;; make sure we keep the old child list. This can cause bugs, but ;; if no new slots are created, it also saves time, and prevents ;; method table breakage, particularly when the users is only @@ -793,7 +794,7 @@ (defun eieio-perform-slot-validation-for-default (slot spec value skipnil) "For SLOT, signal if SPEC does not match VALUE. -If SKIPNIL is non-nil, then if VALUE is nil, return t." +If SKIPNIL is non-nil, then if VALUE is nil return t instead." (let ((val (eieio-default-eval-maybe value))) (if (and (not eieio-skip-typecheck) (not (and skipnil (null val))) @@ -804,10 +805,10 @@ &optional defaultoverride skipnil) "Add into NEWC attribute A. If A already exists in NEWC, then do nothing. If it doesn't exist, -then also add in D (defualt), DOC, TYPE, CUST, LABEL, CUSTG, PRINT, PROT, and INIT arg. +then also add in D (default), DOC, TYPE, CUST, LABEL, CUSTG, PRINT, PROT, and INIT arg. Argument ALLOC specifies if the slot is allocated per instance, or per class. If optional DEFAULTOVERRIDE is non-nil, then if A exists in NEWC, -we must override it's value for a default. +we must override its value for a default. Optional argument SKIPNIL indicates if type checking should be skipped if default value is nil." ;; Make sure we duplicate those items that are sequences. @@ -856,7 +857,7 @@ (tp (if np (nth num (aref newc class-public-type)))) ) (if (not np) - (error "Eieio internal error overriding default value for %s" + (error "EIEIO internal error overriding default value for %s" a) ;; If type is passed in, is it the same? (if (not (eq type t)) @@ -964,7 +965,7 @@ (tp (if np (nth num (aref newc class-class-allocation-type)) nil))) (if (not np) - (error "Eieio internal error overriding default value for %s" + (error "EIEIO internal error overriding default value for %s" a) ;; If type is passed in, is it the same? (if (not (eq type t)) @@ -1121,11 +1122,11 @@ ;;; CLOS methods and generics ;; (defmacro defgeneric (method args &optional doc-string) - "Create a generic function METHOD. ARGS is ignored. + "Create a generic function METHOD. DOC-STRING is the base documentation for this class. A generic -function has no body, as it's purpose is to decide which method body -is appropriate to use. Use `defmethod' to create methods, and it -calls defgeneric for you. With this implementation the arguments are +function has no body, as its purpose is to decide which method body +is appropriate to use. Uses `defmethod' to create methods, and calls +`defgeneric' for you. With this implementation the ARGS are currently ignored. You can use `defgeneric' to apply specialized top level documentation to a method." `(eieio-defgeneric (quote ,method) ,doc-string)) @@ -1242,21 +1243,21 @@ 'method)) (defun eieio-unbind-method-implementations (method) - "Make the generic method METHOD have no implementations.. -It will leave the original generic function in place, but remove -reference to all implementations of METHOD." + "Make the generic method METHOD have no implementations. +It will leave the original generic function in place, +but remove reference to all implementations of METHOD." (put method 'eieio-method-tree nil) (put method 'eieio-method-obarray nil)) (defmacro defmethod (method &rest args) "Create a new METHOD through `defgeneric' with ARGS. -The second optional argument KEY is a specifier that +The optional second argument KEY is a specifier that modifies how the method is called, including: - :before - Method will be called before the :primary - :primary - The default if not specified. - :after - Method will be called after the :primary - :static - First arg could be an object or class + :before - Method will be called before the :primary + :primary - The default if not specified + :after - Method will be called after the :primary + :static - First arg could be an object or class The next argument is the ARGLIST. The ARGLIST specifies the arguments to the method as with `defun'. The first argument can have a type specifier, such as: @@ -1311,7 +1312,7 @@ (eieio-defgeneric method (if (stringp (car body)) - (car body) (format "Generically created method `%s'" method))) + (car body) (format "Generically created method `%s'." method))) ;; create symbol for property to bind to. If the first arg is of ;; the form (varname vartype) and `vartype' is a class, then ;; that class will be the type symbol. If not, then it will fall @@ -1360,10 +1361,10 @@ (typep value spec))) (defun eieio-validate-slot-value (class slot-idx value slot) - "Make sure that for CLASS referencing SLOT-IDX, that VALUE is valid. + "Make sure that for CLASS referencing SLOT-IDX, VALUE is valid. Checks the :type specifier. SLOT is the slot that is being checked, and is only used when throwing -and error." +an error." (if eieio-skip-typecheck nil ;; Trim off object IDX junk added in for the object index. @@ -1373,10 +1374,10 @@ (signal 'invalid-slot-type (list class slot st value)))))) (defun eieio-validate-class-slot-value (class slot-idx value slot) - "Make sure that for CLASS referencing SLOT-IDX, that VALUE is valid. + "Make sure that for CLASS referencing SLOT-IDX, VALUE is valid. Checks the :type specifier. SLOT is the slot that is being checked, and is only used when throwing -and error." +an error." (if eieio-skip-typecheck nil (let ((st (aref (aref (class-v class) class-class-allocation-type) @@ -1418,7 +1419,7 @@ (aref (aref (class-v class) class-class-allocation-values) c) ;; The slot-missing method is a cool way of allowing an object author ;; to intercept missing slot definitions. Since it is also the LAST - ;; thing called in this fn, it's return value would be retrieved. + ;; thing called in this fn, its return value would be retrieved. (slot-missing obj slot 'oref) ;;(signal 'invalid-slot-name (list (object-name obj) slot)) ) @@ -1430,15 +1431,15 @@ (defalias 'set-slot-value 'eieio-oset) (defmacro oref-default (obj slot) - "Gets the default value of OBJ (maybe a class) for SLOT. + "Get the default value of OBJ (maybe a class) for SLOT. The default value is the value installed in a class with the :initform tag. SLOT can be the slot name, or the tag specified by the :initarg tag in the `defclass' call." `(eieio-oref-default ,obj (quote ,slot))) (defun eieio-oref-default (obj slot) - "Does the work for the macro `oref-default' with similar parameters. -Fills in OBJ's SLOT with it's default value." + "Do the work for the macro `oref-default' with similar parameters. +Fills in OBJ's SLOT with its default value." (if (not (or (eieio-object-p obj) (class-p obj))) (signal 'wrong-type-argument (list 'eieio-object-p obj))) (if (not (symbolp slot)) (signal 'wrong-type-argument (list 'symbolp slot))) (let* ((cl (if (eieio-object-p obj) (aref obj object-class) obj)) @@ -1476,7 +1477,7 @@ `(eieio-oset ,obj (quote ,slot) ,value)) (defun eieio-oset (obj slot value) - "Does the work for the macro `oset'. + "Do the work for the macro `oset'. Fills in OBJ's SLOT with VALUE." (if (not (eieio-object-p obj)) (signal 'wrong-type-argument (list 'eieio-object-p obj))) (if (not (symbolp slot)) (signal 'wrong-type-argument (list 'symbolp slot))) @@ -1507,7 +1508,7 @@ `(eieio-oset-default ,class (quote ,slot) ,value)) (defun eieio-oset-default (class slot value) - "Does the work for the macro `oset-default'. + "Do the work for the macro `oset-default'. Fills in the default value in CLASS' in SLOT with VALUE." (if (not (class-p class)) (signal 'wrong-type-argument (list 'class-p class))) (if (not (symbolp slot)) (signal 'wrong-type-argument (list 'symbolp slot))) @@ -1551,7 +1552,7 @@ (VARN+1 SLOTN+1)) Where each VAR is the local variable given to the associated -SLOT. A Slot specified without a variable name is given a +SLOT. A slot specified without a variable name is given a variable name of the same name as the slot." ;; Transform the spec-list into a symbol-macrolet spec-list. (let ((mappings (mapcar (lambda (entry) @@ -1648,7 +1649,7 @@ (defalias 'obj-of-class-p 'object-of-class-p) (defun child-of-class-p (child class) - "If CHILD class is a subclass of CLASS." + "Return non-nil if CHILD class is a subclass of CLASS." (if (not (class-p class)) (signal 'wrong-type-argument (list 'class-p class))) (if (not (class-p child)) (signal 'wrong-type-argument (list 'class-p child))) (let ((p nil)) @@ -1658,7 +1659,7 @@ p (cdr p))) (if child t))) -(defun object-slots (obj) "List of slots available in OBJ." +(defun object-slots (obj) "Return list of slots available in OBJ." (if (not (eieio-object-p obj)) (signal 'wrong-type-argument (list 'eieio-object-p obj))) (aref (class-v (object-class-fast obj)) class-public-a)) @@ -1675,7 +1676,7 @@ ;;; CLOS queries into classes and slots ;; (defun slot-boundp (object slot) - "Non-nil if OBJECT's SLOT is bound. + "Return non-nil if OBJECT's SLOT is bound. Setting a slot's value makes it bound. Calling `slot-makeunbound' will make a slot unbound. OBJECT can be an instance or a class." @@ -1693,7 +1694,7 @@ (eieio-oset object slot eieio-unbound)) (defun slot-exists-p (object-or-class slot) - "Non-nil if OBJECT-OR-CLASS has SLOT." + "Return non-nil if OBJECT-OR-CLASS has SLOT." (let ((cv (class-v (cond ((eieio-object-p object-or-class) (object-class object-or-class)) ((class-p object-or-class) @@ -1716,7 +1717,7 @@ ;; (defun object-assoc (key slot list) "Return an object if KEY is `equal' to SLOT's value of an object in LIST. -LIST is a list of objects who's slots are searched. +LIST is a list of objects whose slots are searched. Objects in LIST do not need to have a slot named SLOT, nor does SLOT need to be bound. If these errors occur, those objects will be ignored." @@ -1781,7 +1782,7 @@ (defun object-remove-from-list (object slot item) "In OBJECT's SLOT, remove occurrences of ITEM. -Deletion is done with `delete', which deletes by side effect +Deletion is done with `delete', which deletes by side effect, and comparisons are done with `equal'. If SLOT is unbound, do nothing." (if (not (slot-boundp object slot)) @@ -1791,7 +1792,7 @@ ;;; EIEIO internal search functions ;; (defun eieio-slot-originating-class-p (start-class slot) - "Return Non-nil if START-CLASS is the first class to define SLOT. + "Return non-nil if START-CLASS is the first class to define SLOT. This is for testing if `scoped-class' is the class that defines SLOT so that we can protect private slots." (let ((par (class-parents start-class)) @@ -1810,7 +1811,7 @@ "In CLASS for OBJ find the index of the named SLOT. The slot is a symbol which is installed in CLASS by the `defclass' call. OBJ can be nil, but if it is an object, and the slot in question -is protected, access will be allowed if obj is a child of the currently +is protected, access will be allowed if OBJ is a child of the currently `scoped-class'. If SLOT is the value created with :initarg instead, reverse-lookup that name, and recurse with the associated slot value." @@ -1869,7 +1870,7 @@ (defvar eieio-pre-method-execution-hooks nil "*Hooks run just before a method is executed. -The hook function must accept on argument, this list of forms +The hook function must accept one argument, the list of forms about to be executed.") (defun eieio-generic-call (method args) @@ -2122,7 +2123,7 @@ (nreverse lambdas)))) (defun next-method-p () - "Non-nil if there is a next method. + "Return non-nil if there is a next method. Returns a list of lambda expressions which is the `next-method' order." eieio-generic-call-next-method-list) @@ -2138,7 +2139,7 @@ Use `next-method-p' to find out if there is a next method to call." (if (not scoped-class) - (error "Call-next-method not called within a class specific method")) + (error "`call-next-method' not called within a class specific method")) (if (and (/= eieio-generic-call-key method-primary) (/= eieio-generic-call-key method-static)) (error "Cannot `call-next-method' except in :primary or :static methods") @@ -2204,7 +2205,7 @@ It also indicates if CLASS is defined or not. CLASS is the class this method is associated with." (if (or (> key method-num-slots) (< key 0)) - (error "Eieiomt-add: method key error!")) + (error "eieiomt-add: method key error!")) (let ((emtv (get method-name 'eieio-method-tree)) (emto (get method-name 'eieio-method-obarray))) ;; Make sure the method tables are available. @@ -2229,10 +2230,10 @@ (defun eieiomt-next (class) "Return the next parent class for CLASS. -If CLASS is a superclass, return variable `eieio-default-superclass'. If CLASS -is variable `eieio-default-superclass' then return nil. This is different from -function `class-parent' as class parent returns nil for superclasses. This -function performs no type checking!" +If CLASS is a superclass, return variable `eieio-default-superclass'. +If CLASS is variable `eieio-default-superclass' then return nil. +This is different from function `class-parent' as class parent returns +nil for superclasses. This function performs no type checking!" ;; No type-checking because all calls are made from functions which ;; are safe and do checking for us. (or (class-parents-fast class) @@ -2249,7 +2250,7 @@ (cont t)) ;; This converts ES from a single symbol to a list of parent classes. (setq es (eieiomt-next es)) - ;; Loop over ES, then it's children individually. + ;; Loop over ES, then its children individually. ;; We can have multiple hits only at one level of the parent tree. (while (and es cont) (setq ov (intern-soft (symbol-name (car es)) eieiomt-optimizing-obarray)) @@ -2271,10 +2272,10 @@ (defun eieio-generic-form (method key class) "Return the lambda form belonging to METHOD using KEY based upon CLASS. -If CLASS is not a class then use `generic' instead. If class has no -form, but has a parent class, then trace to that parent class. The -first time a form is requested from a symbol, an optimized path is -memorized for future faster use." +If CLASS is not a class then use `generic' instead. If class has +no form, but has a parent class, then trace to that parent class. +The first time a form is requested from a symbol, an optimized path +is memorized for future faster use." (let ((emto (aref (get method 'eieio-method-obarray) (if class key (+ key 3))))) (if (class-p class) @@ -2285,7 +2286,7 @@ ;; This can be slow since it only occurs once (progn (setq cs (intern (symbol-name class) emto)) - ;; 2.1) Cache it's nearest neighbor with a quick optimize + ;; 2.1) Cache its nearest neighbor with a quick optimize ;; which should only occur once for this call ever (let ((eieiomt-optimizing-obarray emto)) (eieiomt-sym-optimize cs)))) @@ -2295,7 +2296,7 @@ ;; 4) If it's not bound then this variable knows something (if (symbol-value cs) (progn - ;; 4.1) This symbol holds the next class in it's value + ;; 4.1) This symbol holds the next class in its value (setq class (symbol-value cs) cs (intern-soft (symbol-name class) emto)) ;; 4.2) The optimizer should always have chosen a @@ -2337,7 +2338,7 @@ (defun eieio-initarg-to-attribute (class initarg) "For CLASS, convert INITARG to the actual attribute name. If there is no translation, pass it in directly (so we can cheat if -need be.. May remove that later...)" +need be... May remove that later...)" (let ((tuple (assoc initarg (aref (class-v class) class-initarg-tuples)))) (if tuple (cdr tuple) @@ -2405,18 +2406,18 @@ (defclass eieio-default-superclass nil nil "Default parent class for classes with no specified parent class. -Its slots are automatically adopted by classes with no specified -parents. This class is not stored in the `parent' slot of a class vector." +Its slots are automatically adopted by classes with no specified parents. +This class is not stored in the `parent' slot of a class vector." :abstract t) (defalias 'standard-class 'eieio-default-superclass) (defgeneric constructor (class newname &rest slots) - "Default constructor for CLASS `eieio-defualt-superclass'.") + "Default constructor for CLASS `eieio-default-superclass'.") (defmethod constructor :static ((class eieio-default-superclass) newname &rest slots) - "Default constructor for CLASS `eieio-defualt-superclass'. + "Default constructor for CLASS `eieio-default-superclass'. NEWNAME is the name to be given to the constructed object. SLOTS are the initialization slots used by `shared-initialize'. This static method is called when an object is constructed. @@ -2449,17 +2450,17 @@ (setq slots (cdr (cdr slots)))))) (defgeneric initialize-instance (this &optional slots) - "Constructs the new object THIS based on SLOTS.") + "Construct the new object THIS based on SLOTS.") (defmethod initialize-instance ((this eieio-default-superclass) &optional slots) - "Constructs the new object THIS based on SLOTS. + "Construct the new object THIS based on SLOTS. SLOTS is a tagged list where odd numbered elements are tags, and -even numbered elements are the values to store in the tagged slot. If -you overload the `initialize-instance', there you will need to call -`shared-initialize' yourself, or you can call `call-next-method' to -have this constructor called automatically. If these steps are not -taken, then new objects of your class will not have their values +even numbered elements are the values to store in the tagged slot. +If you overload the `initialize-instance', there you will need to +call `shared-initialize' yourself, or you can call `call-next-method' +to have this constructor called automatically. If these steps are +not taken, then new objects of your class will not have their values dynamically set from SLOTS." ;; First, see if any of our defaults are `lambda', and ;; re-evaluate them and apply the value to our slots. @@ -2526,9 +2527,9 @@ &rest args) "Called from `call-next-method' when no additional methods are available. OBJECT is othe object being called on `call-next-method'. -ARGS are the arguments it is called by. +ARGS are the arguments it is called by. This method signals `no-next-method' by default. Override this -method to not throw an error, and it's return value becomes the +method to not throw an error, and its return value becomes the return value of `call-next-method'." (signal 'no-next-method (list (object-name object) args)) ) @@ -2570,7 +2571,7 @@ "Pretty printer for object THIS. Call function `object-name' with STRINGS. It is sometimes useful to put a summary of the object into the -default #<notation> string when using eieio browsing tools. +default #<notation> string when using EIEIO browsing tools. Implement this method to customize the summary.") (defmethod object-print ((this eieio-default-superclass) &rest strings) @@ -2579,7 +2580,7 @@ function `object-name'. It is sometimes useful to put a summary of the object into the -default #<notation> string when using eieio browsing tools. +default #<notation> string when using EIEIO browsing tools. Implement this function and specify STRINGS in a call to `call-next-method' to provide additional summary information. @@ -2592,7 +2593,7 @@ (defgeneric object-write (this &optional comment) "Write out object THIS to the current stream. -Optional COMMENDS will add comments to the beginning of the output.") +Optional COMMENT will add comments to the beginning of the output.") (defmethod object-write ((this eieio-default-superclass) &optional comment) "Write object THIS out to the current stream. @@ -2644,7 +2645,7 @@ (princ ")\n"))) (defun eieio-override-prin1 (thing) - "Perform a prin1 on THING taking advantage of object knowledge." + "Perform a `prin1' on THING taking advantage of object knowledge." (cond ((eieio-object-p thing) (object-write thing)) ((listp thing) @@ -2680,7 +2681,7 @@ "Change the class of OBJ to type CLASS. This may create or delete slots, but does not affect the return value of `eq'." - (error "Eieio: `change-class' is unimplemented")) + (error "EIEIO: `change-class' is unimplemented")) ) @@ -2688,7 +2689,8 @@ ;;; Interfacing with edebug ;; (defun eieio-edebug-prin1-to-string (object &optional noescape) - "Display eieio OBJECT in fancy format. Overrides the edebug default. + "Display EIEIO OBJECT in fancy format. +Overrides the edebug default. Optional argument NOESCAPE is passed to `prin1-to-string' when appropriate." (cond ((class-p object) (class-name object)) ((eieio-object-p object) (object-print object))