bug#36392: (info "(elisp)Writing Emacs Primitives") might need some clarifications

[Eli Zaretskii]

> From: "Basil L. Contovounesios" <contovob@tcd.ie>
> Date: Wed, 26 Jun 2019 14:09:03 +0100
> Cc: 36392@debbugs.gnu.org
> 
> >From 3d85d73858fe0c126277d04db8b99eeb9f09d672 Mon Sep 17 00:00:00 2001
> From: "Basil L. Contovounesios" <contovob@tcd.ie>
> Date: Wed, 26 Jun 2019 13:05:51 +0100
> Subject: [PATCH] Clarify & update (elisp) Writing Emacs Primitives
> 
> * doc/lispref/internals.texi (Writing Emacs Primitives): Replace
> outdated For listing with current Fwhile, so that the subsequent
> paragraph on maybe_quit still applies.  Reconcile other code
> listings with their current source.  Fix indentation of sample DEFUN
> argument lists.  Replace ... with @dots{}.  Fix argument list of
> Ffoo example.  Describe UNEVALLED special forms as taking a single
> argument. (bug#36392)

Hmm... I admit that I don't understand the rationale for these
changes.

Why replace the example?  It's a useful example, and I see nothing
wrong with it per se.  The actual code doesn't have maybe_quit
anymore, but so what?  I don't think we should chace every change in
the sources with our examples in the manual.

> @@ -863,20 +860,23 @@ Writing Emacs Primitives
>  arguments, there must be one C argument for each Lisp argument, and
>  each argument must be of type @code{Lisp_Object}.  (Various macros and
>  functions for creating values of type @code{Lisp_Object} are declared
> -in the file @file{lisp.h}.)  If the primitive has no upper limit on
> -the number of Lisp arguments, it must have exactly two C arguments:
> -the first is the number of Lisp arguments, and the second is the
> -address of a block containing their values.  These have types
> -@code{int} and @w{@code{Lisp_Object *}} respectively.  Since
> -@code{Lisp_Object} can hold any Lisp object of any data type, you
> -can determine the actual data type only at run time; so if you want
> -a primitive to accept only a certain type of argument, you must check
> -the type explicitly using a suitable predicate (@pxref{Type Predicates}).
> +in the file @file{lisp.h}.)  If the primitive is a special form, it
> +must accept a Lisp list containing its unevaluated Lisp arguments as a
> +single argument of type @code{Lisp_Object}.  If the primitive has no
> +upper limit on the number of evaluated Lisp arguments, it must have
> +exactly two C arguments: the first is the number of Lisp arguments,
> +and the second is the address of a block containing their values.
> +These have types @code{ptrdiff_t} and @w{@code{Lisp_Object *}},
> +respectively.  Since @code{Lisp_Object} can hold any Lisp object of
> +any data type, you can determine the actual data type only at run
> +time; so if you want a primitive to accept only a certain type of
> +argument, you must check the type explicitly using a suitable
> +predicate (@pxref{Type Predicates}).
>  @cindex type checking internals

This part sounds OK to me, and is probably more than enough to fix the
issue at hand.

> -    case ON_NOTHING:            /* NOT in window at all.  */
> +    case ON_NOTHING:

This seems a change for the worst?

> > 2.  "Although the garbage collector does not reclaim objects reachable
> >     from C ‘Lisp_Object’ stack variables, it may move non-object
> >     components of an object, such as string contents; so functions
> >     that access non-object components must take care to refetch their
> >     addresses after performing Lisp evaluation."
> >
> > I don't think this is very clear.  What is non-object components?  How
> > would I refetch their addresses?  How is this relevant to the topic at
> > hand?
> 
> I don't know about this.

I clarified that.

Thanks.