master bef3070 2/2: Merge from origin/emacs-27

[Glenn Morris]

branch: master
commit bef3070ab8dfbb8b68c08f0f0aa03532311f3dd5
Merge: 6456a67 37f4457
Author: Glenn Morris <rgm@gnu.org>
Commit: Glenn Morris <rgm@gnu.org>

    Merge from origin/emacs-27
    
    37f4457994 (origin/emacs-27) ; Fix typo in dynamic module functions d...
    f7d4bbceee ; * src/composite.h: Improve comments for LGSTRING and LGL...
---
 doc/lispref/internals.texi |  2 +-
 src/composite.h            | 17 +++++++++++++++++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index 4150a2b..0e250d0 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -1429,7 +1429,7 @@ other words, if a module function wants to call Lisp 
functions or
 Emacs primitives, convert @code{emacs_value} objects to and from C
 datatypes (@pxref{Module Values}), or interact with Emacs in any other
 way, some call from Emacs to @code{emacs_module_init} or to a module
-function must be in the call stack.  Module function may not interact
+function must be in the call stack.  Module functions may not interact
 with Emacs while garbage collection is running; @pxref{Garbage
 Collection}.  They may only interact with Emacs from Lisp interpreter
 threads (including the main thread) created by Emacs; @pxref{Threads}.
diff --git a/src/composite.h b/src/composite.h
index 660b1fa..67e8720 100644
--- a/src/composite.h
+++ b/src/composite.h
@@ -246,6 +246,11 @@ composition_valid_p (ptrdiff_t start, ptrdiff_t end, 
Lisp_Object prop)
 /* Macros for lispy glyph-string.  This is completely different from
    struct glyph_string.  */
 
+/* LGSTRING is a string of font glyphs, LGLYPHs.  It is represented as
+   a Lisp vector, with components shown below.  Once LGSTRING was
+   processed by a shaping engine, it holds font glyphs for one or more
+   grapheme clusters.  */
+
 #define LGSTRING_HEADER(lgs) AREF (lgs, 0)
 #define LGSTRING_SET_HEADER(lgs, header) ASET (lgs, 0, header)
 
@@ -259,6 +264,10 @@ composition_valid_p (ptrdiff_t start, ptrdiff_t end, 
Lisp_Object prop)
 #define LGSTRING_ID(lgs) AREF (lgs, 1)
 #define LGSTRING_SET_ID(lgs, id) ASET (lgs, 1, id)
 
+/* LGSTRING_GLYPH_LEN is the maximum number of LGLYPHs that the
+   LGSTRING can hold.  This is NOT the actual number of valid LGLYPHs;
+   to find the latter, walk the glyphs returned by LGSTRING_GLYPH
+   until the first one that is nil.  */
 #define LGSTRING_GLYPH_LEN(lgs) (ASIZE ((lgs)) - 2)
 #define LGSTRING_GLYPH(lgs, idx) AREF ((lgs), (idx) + 2)
 #define LGSTRING_SET_GLYPH(lgs, idx, val) ASET ((lgs), (idx) + 2, (val))
@@ -278,6 +287,14 @@ enum lglyph_indices
     LGLYPH_SIZE
   };
 
+/* Each LGLYPH is a single font glyph, whose font code is in
+   LGLYPH_CODE.
+   LGLYPH_FROM and LGLYPH_TO are indices into LGSTRING; all the
+   LGLYPHs that share the same values of LGLYPH_FROM and LGLYPH_TO
+   belong to the same grapheme cluster.
+   LGLYPH_CHAR is one of the characters, usually the first one, that
+   contributed to the glyph (since there isn't a 1:1 correspondence
+   between composed characters and the font glyphs).  */
 #define LGLYPH_NEW() make_nil_vector (LGLYPH_SIZE)
 #define LGLYPH_FROM(g) XFIXNUM (AREF ((g), LGLYPH_IX_FROM))
 #define LGLYPH_TO(g) XFIXNUM (AREF ((g), LGLYPH_IX_TO))