Subject: Re: bug#38598: 26.3; Document relation between `make-symbol` and `gensym`
From: Eli Zaretskii <[email-masked]>
To: Drew Adams <[email-masked]>
Cc: [email-masked]
Date: Sat, 14 Dec 2019 11:30:00 +0200
List-Id: <debbugs-submit.debbugs.gnu.org>

> Date: Fri, 13 Dec 2019 12:35:13 -0800 (PST)
> From: Drew Adams <[email-masked]>
> 
> (See https://emacs.stackexchange.com/a/54361/105.)
> 
> The Common-Lisp doc is clear about the similarity and difference between
> `make-symbol` and `gensym`.  The Emacs-Lisp doc says nothing about this.
> 
> Please consider mentioning this in (elisp) `Creating Symbols'.  Such
> info can help users better understand when they might want to use one or
> the other of these functions.
> 
> Yes, this info can be gleaned by carefully reading their individual
> descriptions (how the symbol-naming is done).  But it would help users
> to state it clearly.

Thanks, but I find the current documentation clear enough:

 -- Function: make-symbol name
     This function returns a newly-allocated, uninterned symbol whose
     name is NAME (which must be a string).  Its value and function
     definition are void, and its property list is ‘nil’.  In the
     example below, the value of ‘sym’ is not ‘eq’ to ‘foo’ because it
     is a distinct uninterned symbol whose name is also ‘foo’.

          (setq sym (make-symbol "foo"))
               ⇒ foo
          (eq sym 'foo)
               ⇒ nil

 -- Function: gensym &optional prefix
     This function returns a symbol using ‘make-symbol’, whose name is
     made by appending ‘gensym-counter’ to PREFIX.  The prefix defaults
     to ‘"g"’.

I see nothing that could be gained by adding any explicit sentence
about the difference, since that would simply be a rewording of what
is already said right there.

So I'm closing this bug report.