Fix outdated comments.

1 files changed, 59 insertions, 23 deletions

diff --git a/src/fontset.c b/src/fontset.c
index 9429d79b6b9..0f89b71ff68 100644
--- a/src/fontset.c
+++ b/src/fontset.c
@@ -63,17 +63,26 @@ along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.  */
    An element of a base fontset is a vector of FONT-DEFs which themselves
    are vectors of the form [ FONT-SPEC ENCODING REPERTORY ].
 
-   An element of a realized fontset is nil, t, 0, or a vector of this
-   form:
+   An element of a realized fontset is nil, t, 0, or a cons that has
+   this from:
 
-        [ PREFERRED-RFONT-DEF RFONT-DEF0 RFONT-DEF1 ... ]
+        (CHARSET-ORDERED-LIST-TICK . FONT-GROUP)
+
+   CHARSET_ORDERED_LIST_TICK is the same as charset_ordered_list_tick or -1.
+
+   FONT-GROUP is a vector of elements that have this form:
+
+        [ RFONT-DEF0 RFONT-DEF1 ... ]
 
    Each RFONT-DEFn (i.e. Realized FONT-DEF) has this form:
 
         [ FACE-ID FONT-DEF FONT-OBJECT SORTING-SCORE ]
 
-   RFONT-DEFn are automatically reordered by the current charset
-   priority list.
+   RFONT-DEFn are automatically reordered considering the current
+   charset priority list, the current language environment, and
+   priorities determined by font-backends.
+
+   RFONT-DEFn may not be a vector in the following cases.
 
    The value nil means that we have not yet generated the above vector
    from the base of the fontset.
@@ -83,7 +92,7 @@ along with GNU Emacs.  If not, see <http://www.gnu.org/licenses/>.  */
 
    The value 0 means that no font is available for the corresponding
    range of characters in this fontset, but may be available in the
-   default fontset.
+   fallback font-group or in the default fontset.
 
    A fontset has 8 extra slots.
 
@@ -407,6 +416,9 @@ reorder_font_vector (Lisp_Object font_group, struct font *font)
 
           if (! NILP (encoding))
             {
+              /* This spec specifies an encoding by a charset set
+                 name.  Reflect the preference order of that charset
+                 in the upper bits of SCORE.  */
               Lisp_Object tail;
 
               for (tail = Vcharset_ordered_list;
@@ -419,6 +431,10 @@ reorder_font_vector (Lisp_Object font_group, struct font *font)
             }
           else
             {
+              /* This spec does not specify an encoding.  If the spec
+                 specifies a language, and the language is not for the
+                 current language environment, make the score
+                 larger.  */
               Lisp_Object lang = Ffont_get (font_spec, QClang);
 
               if (! NILP (lang)
@@ -442,11 +458,11 @@ reorder_font_vector (Lisp_Object font_group, struct font *font)
   XSETCAR (font_group, make_number (low_tick_bits));
 }
 
-/* Return a font-group (actually a cons (-1 . FONT-GROUP-VECTOR)) for
-   character C in FONTSET.  If C is -1, return a fallback font-group.
-   If C is not -1, the value may be Qt (FONTSET doesn't have a font
-   for C even in the fallback group), or 0 (a font for C may be found
-   only in the fallback group).  */
+/* Return a font-group (actually a cons (CHARSET_ORDERED_LIST_TICK
+   . FONT-GROUP)) for character C or a fallback font-group in the
+   realized fontset FONTSET.  The elements of FONT-GROUP are
+   RFONT-DEFs.  The value may not be a cons.  See the comment at the
+   head of this file for the detail of the return value.  */
 
 static Lisp_Object
 fontset_get_font_group (Lisp_Object fontset, int c)
@@ -461,23 +477,37 @@ fontset_get_font_group (Lisp_Object fontset, int c)
   else
     font_group = FONTSET_FALLBACK (fontset);
   if (! NILP (font_group))
+    /* We have already realized FONT-DEFs of this font group for C or
+       for fallback (FONT_GROUP is a cons), or we have already found
+       that no appropriate font was found (FONT_GROUP is t or 0).  */
     return font_group;
   base_fontset = FONTSET_BASE (fontset);
   if (NILP (base_fontset))
+    /* Actually we never come here because FONTSET is a realized one,
+       and thus it should have a base.  */
     font_group = Qnil;
   else if (c >= 0)
     font_group = char_table_ref_and_range (base_fontset, c, &from, &to);
   else
     font_group = FONTSET_FALLBACK (base_fontset);
+
+  /* FONT_GROUP not being a vector means that no fonts are specified
+     for C, or the fontset does not have fallback fonts.  */
   if (NILP (font_group))
     {
       font_group = make_number (0);
       if (c >= 0)
+        /* Record that FONTSET does not specify fonts for C.  As
+           there's a possiblity that a font is found in a fallback
+           font group, we set 0 at the moment.  */
         char_table_set_range (fontset, from, to, font_group);
       return font_group;
     }
   if (!VECTORP (font_group))
     return font_group;
+
+  /* Now realize FONT-DEFs of this font group, and update the realized
+     fontset FONTSET. */
   font_group = Fcopy_sequence (font_group);
   for (i = 0; i < ASIZE (font_group); i++)
     if (! NILP (AREF (font_group, i)))
@@ -498,21 +528,21 @@ fontset_get_font_group (Lisp_Object fontset, int c)
 }
 
 /* Return RFONT-DEF (vector) in the realized fontset FONTSET for the
-   character C.  If no font is found, return Qnil if there's a
+   character C.  If no font is found, return Qnil or 0 if there's a
    possibility that the default fontset or the fallback font groups
    have a proper font, and return Qt if not.
 
    If a font is found but is not yet opened, open it (if FACE is not
    NULL) or return Qnil (if FACE is NULL).
 
-   ID is a charset-id that must be preferred, or -1 meaning no
+   CHARSET_ID is a charset-id that must be preferred, or -1 meaning no
    preference.
 
    If FALLBACK, search only fallback fonts.  */
 
 static Lisp_Object
-fontset_find_font (Lisp_Object fontset, int c, struct face *face, int id,
-                   bool fallback)
+fontset_find_font (Lisp_Object fontset, int c, struct face *face, 
+                   int charset_id, bool fallback)
 {
   Lisp_Object vec, font_group;
   int i, charset_matched = 0, found_index;
@@ -534,8 +564,8 @@ fontset_find_font (Lisp_Object fontset, int c, struct face *face, int id,
         /* We have just created the font-group,
            or the charset priorities were changed.  */
         reorder_font_vector (font_group, face->ascii_face->font);
-      if (id >= 0)
-        /* Find a spec matching with the charset ID to try at
+      if (charset_id >= 0)
+        /* Find a spec matching with CHARSET_ID to try it at
            first.  */
         for (i = 0; i < ASIZE (vec); i++)
           {
@@ -546,7 +576,7 @@ fontset_find_font (Lisp_Object fontset, int c, struct face *face, int id,
               break;
             repertory = FONT_DEF_REPERTORY (RFONT_DEF_FONT_DEF (rfont_def));
 
-            if (XINT (repertory) == id)
+            if (XINT (repertory) == charset_id)
               {
                 charset_matched = i;
                 break;
@@ -554,7 +584,9 @@ fontset_find_font (Lisp_Object fontset, int c, struct face *face, int id,
           }
     }
 
-  /* Find the first available font in the vector of RFONT-DEF.  */
+  /* Find the first available font in the vector of RFONT-DEF.  If
+     CHARSET_MATCHED > 0, try the correspoing RFONT-DEF first, then
+     try the rest.  */
   for (i = 0; i < ASIZE (vec); i++)
     {
       Lisp_Object font_def;
@@ -565,13 +597,13 @@ fontset_find_font (Lisp_Object fontset, int c, struct face *face, int id,
         {
           if (charset_matched > 0)
             {
-              /* Try the element matching with the charset ID at first.  */
+              /* Try the element matching with CHARSET_ID at first.  */
               found_index = charset_matched;
               /* Make this negative so that we don't come here in the
                  next loop.  */
               charset_matched = - charset_matched;
               /* We must try the first element in the next loop.  */
-              i--;
+              i = -1;
             }
         }
       else if (i == - charset_matched)
@@ -630,10 +662,10 @@ fontset_find_font (Lisp_Object fontset, int c, struct face *face, int id,
           if (NILP (font_object))
             {
               /* Something strange happened, perhaps because of a
-                 Font-backend problem.  Too avoid crashing, record
+                 Font-backend problem.  To avoid crashing, record
                  that this spec is unusable.  It may be better to find
                  another font of the same spec, but currently we don't
-                 have such an API.  */
+                 have such an API in font-backend.  */
               RFONT_DEF_SET_FACE (rfont_def, -1);
               continue;
             }
@@ -693,6 +725,7 @@ fontset_find_font (Lisp_Object fontset, int c, struct face *face, int id,
         i = found_index;
     }
 
+  /* Record that no font in this font group supports C.  */
   FONTSET_SET (fontset, make_number (c), make_number (0));
   return Qnil;
 
@@ -711,6 +744,9 @@ fontset_find_font (Lisp_Object fontset, int c, struct face *face, int id,
 }
 
 
+/* Return RFONT-DEF (vector) corresponding to the font for character
+   C.  The value is not a vector if no font is found for C.  */
+
 static Lisp_Object
 fontset_font (Lisp_Object fontset, int c, struct face *face, int id)
 {