bug#31660: 26.1.50; EIEIO manual's Quick Start example makes Emacs unusable

[Gemini Lasswell <gazally@runbox.com>]

[-- 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