* bug#31660: 26.1.50; EIEIO manual's Quick Start example makes Emacs unusable
2018-06-03 0:23 ` Noam Postavsky
@ 2018-11-22 22:01 ` Gemini Lasswell
2019-04-09 23:10 ` Noam Postavsky
0 siblings, 1 reply; 4+ messages in thread
From: Gemini Lasswell @ 2018-11-22 22:01 UTC (permalink / raw)
To: Noam Postavsky; +Cc: 31660
[-- Attachment #1: Type: text/plain, Size: 365 bytes --]
Noam Postavsky <npostavs@gmail.com> writes:
> Gemini Lasswell <gazally@runbox.com> writes:
>
>> Definitely the name of the class in the examples in the manual should be
>> changed, so that the examples work.
>
> Yeah.
Here's a patch to eieio.texi which makes the examples work, and adds a
suggestion to check for name conflicts to the description of 'defclass':
[-- Attachment #2: 0001-Address-name-conflicts-in-EIEIO-documentation-bug-31.patch --]
[-- Type: text/plain, Size: 6125 bytes --]
From 81fa42ad5ad73bb789ad3edc6e06c9d91edbc997 Mon Sep 17 00:00:00 2001
From: Gemini Lasswell <gazally@runbox.com>
Date: Thu, 22 Nov 2018 13:00:03 -0800
Subject: [PATCH] Address name conflicts in EIEIO documentation (bug#31660)
* doc/misc/eieio.texi (Quick Start): Rename the class used in the
example from 'record' to 'person'.
(Building Classes): Advise user to check for name conflicts before
naming a class. Add a missing apostrophe.
(Making New Objects): Correct grammar. Rename the class used in the
example from 'record' to 'my-class'.
---
doc/misc/eieio.texi | 49 +++++++++++++++++++++++++--------------------
1 file changed, 27 insertions(+), 22 deletions(-)
diff --git a/doc/misc/eieio.texi b/doc/misc/eieio.texi
index 689ff72b72..1ad1733762 100644
--- a/doc/misc/eieio.texi
+++ b/doc/misc/eieio.texi
@@ -88,11 +88,11 @@ Quick Start
use @eieio{} to create classes, methods for those classes, and
instances of classes.
-Here is a simple example of a class named @code{record}, containing
+Here is a simple example of a class named @code{person}, containing
three slots named @code{name}, @code{birthday}, and @code{phone}:
@example
-(defclass record () ; No superclasses
+(defclass person () ; No superclasses
((name :initarg :name
:initform ""
:type string
@@ -106,23 +106,23 @@ Quick Start
(phone :initarg :phone
:initform ""
:documentation "Phone number."))
- "A single record for tracking people I know.")
+ "A class for tracking people I know.")
@end example
Each class can have methods, which are defined like this:
@example
-(cl-defmethod call-record ((rec record) &optional scriptname)
- "Dial the phone for the record REC.
+(cl-defmethod call-person ((pers person) &optional scriptname)
+ "Dial the phone for the person PERS.
Execute the program SCRIPTNAME to dial the phone."
- (message "Dialing the phone for %s" (oref rec name))
+ (message "Dialing the phone for %s" (oref pers name))
(shell-command (concat (or scriptname "dialphone.sh")
" "
- (oref rec phone))))
+ (oref pers phone))))
@end example
@noindent
-In this example, the first argument to @code{call-record} is a list,
+In this example, the first argument to @code{call-person} is a list,
of the form (@var{varname} @var{classname}). @var{varname} is the
name of the variable used for the first argument; @var{classname} is
the name of the class that is expected as the first argument for this
@@ -130,17 +130,17 @@ Quick Start
@eieio{} dispatches methods based on the type of the first argument.
You can have multiple methods with the same name for different classes
-of object. When the @code{call-record} method is called, the first
+of object. When the @code{call-person} method is called, the first
argument is examined to determine the class of that argument, and the
method matching the input type is then executed.
Once the behavior of a class is defined, you can create a new
-object of type @code{record}. Objects are created by calling the
+object of type @code{person}. Objects are created by calling the
constructor. The constructor is a function with the same name as your
class which returns a new instance of that class. Here is an example:
@example
-(setq rec (record :name "Eric" :birthday "June" :phone "555-5555"))
+(setq pers (person :name "Eric" :birthday "June" :phone "555-5555"))
@end example
@noindent
@@ -157,19 +157,19 @@ Quick Start
method defined for it. In this example it would look like this:
@example
-(call-record rec)
+(call-person pers)
@end example
@noindent
or
@example
-(call-record rec "my-call-script")
+(call-person pers "my-call-script")
@end example
In these examples, @eieio{} automatically examines the class of
-@code{rec}, and ensures that the method defined above is called. If
-@code{rec} is some other class lacking a @code{call-record} method, or
+@code{pers}, and ensures that the method defined above is called. If
+@code{pers} is some other class lacking a @code{call-person} method, or
some other data type, Emacs signals a @code{cl-no-applicable-method}
error. @ref{Signals}.
@@ -270,10 +270,15 @@ Building Classes
the class as a symbol property of @var{class-name} (@pxref{Symbol
Components,,,elisp,GNU Emacs Lisp Reference Manual}).
+When defining a class, @eieio{} overwrites any preexisting variable or
+function bindings for the symbol @var{class-name}, which may lead to
+undesired consequences. Before naming a new class, you should check
+for name conflicts.
+
The @var{class-name} symbol's variable documentation string is a
modified version of the doc string found in @var{options-and-doc}.
Each time a method is defined, the symbol's documentation string is
-updated to include the methods documentation as well.
+updated to include the method's documentation as well.
The parent classes for @var{class-name} is @var{superclass-list}.
Each element of @var{superclass-list} must be a class. These classes
@@ -625,10 +630,10 @@ Class Options
@node Making New Objects
@chapter Making New Objects
-Suppose we have a simple class is defined, such as:
+Suppose we have defined a simple class, such as:
@example
-(defclass record ()
+(defclass my-class ()
( ) "Doc String")
@end example
@@ -636,10 +641,10 @@ Making New Objects
It is now possible to create objects of that class type.
Calling @code{defclass} has defined two new functions. One is the
-constructor @var{record}, and the other is the predicate,
-@var{record}-p.
+constructor @var{my-class}, and the other is the predicate,
+@var{my-class}-p.
-@defun record object-name &rest slots
+@defun my-class object-name &rest slots
This creates and returns a new object. This object is not assigned to
anything, and will be garbage collected if not saved. This object
@@ -657,7 +662,7 @@ Making New Objects
Example of creating an object from a class:
@example
-(record :value 3 :reference nil)
+(my-class :value 3 :reference nil)
@end example
@end defun
--
2.18.1
^ permalink raw reply related [flat|nested] 4+ messages in thread