Refactor.

* gettext-tools/src/read-catalog-abstract.h: Improve comments.
* gettext-tools/src/read-catalog-abstract.c: Likewise.
* gettext-tools/src/read-catalog.h: Likewise.
* gettext-tools/src/read-catalog.c: Likewise.

diff --git a/gettext-tools/src/read-catalog-abstract.c b/gettext-tools/src/read-catalog-abstract.c
index 3b1c12d9121c6a8051221caa4612a2d15a555546..f1ed9f4086bff02898f44a8446468d15da40444c 100644 (file)
--- a/gettext-tools/src/read-catalog-abstract.c
+++ b/gettext-tools/src/read-catalog-abstract.c
@@ -1,4 +1,4 @@
-/* Reading PO files, abstract class.
+/* Reading textual message catalogs (such as PO files), abstract class.
    Copyright (C) 1995-2024 Free Software Foundation, Inc.
 
    This file was written by Peter Miller <millerp@canb.auug.org.au>

diff --git a/gettext-tools/src/read-catalog-abstract.h b/gettext-tools/src/read-catalog-abstract.h
index 282dcb155b0a36780c0f78550e55e0f704359dfa..951c16979e28723d6bf6e1ee91cb4d530f82ed3f 100644 (file)
--- a/gettext-tools/src/read-catalog-abstract.h
+++ b/gettext-tools/src/read-catalog-abstract.h
@@ -1,4 +1,4 @@
-/* Reading PO files, abstract class.
+/* Reading textual message catalogs (such as PO files), abstract class.
    Copyright (C) 1995-2024 Free Software Foundation, Inc.
 
    This file was written by Peter Miller <millerp@canb.auug.org.au>
@@ -38,6 +38,11 @@ extern "C" {
    help of an OO compiler.  This implementation allows polymorphism
    and inheritance - more than enough for the immediate needs.  */
 
+/* This abstract base class implements the parsing of the catalog file.
+   Several syntaxes are supported (see type catalog_input_format_ty below).
+   Derived classes implement methods that are invoked when a particular
+   element (message, comment, etc.) is seen.  */
+
 /* Forward declaration.  */
 struct abstract_catalog_reader_ty;
 
@@ -51,13 +56,13 @@ typedef struct abstract_catalog_reader_class_ty
         abstract_catalog_reader_class_ty;
 struct abstract_catalog_reader_class_ty
 {
-  /* how many bytes to malloc for an instance of this class */
+  /* How many bytes to malloc for an instance of this class.  */
   size_t size;
 
-  /* what to do immediately after the instance is malloc()ed */
+  /* What to do immediately after the instance is malloc()ed.  */
   void (*constructor) (struct abstract_catalog_reader_ty *pop);
 
-  /* what to do immediately before the instance is free()ed */
+  /* What to do immediately before the instance is free()ed.  */
   void (*destructor) (struct abstract_catalog_reader_ty *pop);
 
   /* This method is invoked before the parse, but after the file is
@@ -70,10 +75,10 @@ struct abstract_catalog_reader_class_ty
      functions.  */
   void (*parse_debrief) (struct abstract_catalog_reader_ty *pop);
 
-  /* what to do with a domain directive */
+  /* What to do with a domain directive.  */
   void (*directive_domain) (struct abstract_catalog_reader_ty *pop, char *name);
 
-  /* what to do with a message directive */
+  /* What to do with a message directive.  */
   void (*directive_message) (struct abstract_catalog_reader_ty *pop,
                              char *msgctxt,
                              char *msgid, lex_pos_ty *msgid_pos,
@@ -84,25 +89,25 @@ struct abstract_catalog_reader_class_ty
                              char *prev_msgid, char *prev_msgid_plural,
                              bool force_fuzzy, bool obsolete);
 
-  /* What to do with a plain-vanilla comment - the expectation is that
+  /* What to do with a plain-vanilla comment.  The expectation is that
      they will be accumulated, and added to the next message
      definition seen.  Or completely ignored.  */
   void (*comment) (struct abstract_catalog_reader_ty *pop, const char *s);
 
   /* What to do with a comment that starts with a dot (i.e. extracted
-     by xgettext) - the expectation is that they will be accumulated,
+     by xgettext).  The expectation is that they will be accumulated,
      and added to the next message definition seen.  Or completely
      ignored.  */
   void (*comment_dot) (struct abstract_catalog_reader_ty *pop, const char *s);
 
   /* What to do with a file position seen in a comment (i.e. a message
-     location comment extracted by xgettext) - the expectation is that
+     location comment extracted by xgettext).  The expectation is that
      they will be accumulated, and added to the next message
      definition seen.  Or completely ignored.  */
   void (*comment_filepos) (struct abstract_catalog_reader_ty *pop,
                            const char *file_name, size_t line_number);
 
-  /* What to do with a comment that starts with a ',' or '!' - this is a
+  /* What to do with a comment that starts with a ',' or '!'; this is a
      special comment.  One of the possible uses is to indicate a
      inexact translation.  */
   void (*comment_special) (struct abstract_catalog_reader_ty *pop,

diff --git a/gettext-tools/src/read-catalog.c b/gettext-tools/src/read-catalog.c
index 10bf977626ae498229530def7b01ef785798d814..ef533fa817ab8bef74e8dc3452ff61c4ddbdff37 100644 (file)
--- a/gettext-tools/src/read-catalog.c
+++ b/gettext-tools/src/read-catalog.c
@@ -1,4 +1,4 @@
-/* Reading PO files.
+/* Reading textual message catalogs (such as PO files).
    Copyright (C) 1995-2024 Free Software Foundation, Inc.
    This file was written by Peter Miller <millerp@canb.auug.org.au>
 

diff --git a/gettext-tools/src/read-catalog.h b/gettext-tools/src/read-catalog.h
index 97358dc94c288ae815ee455042a0def6ae4105c5..4b0dbd2c677510779be7689d2a504986c3a2ec8b 100644 (file)
--- a/gettext-tools/src/read-catalog.h
+++ b/gettext-tools/src/read-catalog.h
@@ -1,4 +1,4 @@
-/* Reading PO files.
+/* Reading textual message catalogs (such as PO files).
    Copyright (C) 1995-2024 Free Software Foundation, Inc.
    This file was written by Bruno Haible <haible@clisp.cons.org>.
 
@@ -37,8 +37,14 @@ extern "C" {
 
 /* The following pair of structures cooperate to create a derived class from
    class abstract_catalog_reader_ty.  (See read-catalog-abstract.h for an
-   explanation.)  It implements the default behaviour of reading a PO file
-   and converting it to an 'msgdomain_list_ty *'.  */
+   explanation.)
+
+   This derived class stores the contents of the message catalog in memory,
+   converting it to an 'msgdomain_list_ty *'.
+
+   It is called the "default" catalog reader because useful variants can be
+   implemented with little effort by creating a derived class of class
+   default_catalog_reader_ty.  */
 
 /* Forward declaration.  */
 struct default_catalog_reader_ty;