From c1d5e752d4395c18395587fa0a6c566592efb750 Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Sun, 28 Jul 2024 13:42:43 +0200 Subject: [PATCH] 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. --- gettext-tools/src/read-catalog-abstract.c | 2 +- gettext-tools/src/read-catalog-abstract.h | 25 ++++++++++++++--------- gettext-tools/src/read-catalog.c | 2 +- gettext-tools/src/read-catalog.h | 12 ++++++++--- 4 files changed, 26 insertions(+), 15 deletions(-) diff --git a/gettext-tools/src/read-catalog-abstract.c b/gettext-tools/src/read-catalog-abstract.c index 3b1c12d91..f1ed9f408 100644 --- 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 diff --git a/gettext-tools/src/read-catalog-abstract.h b/gettext-tools/src/read-catalog-abstract.h index 282dcb155..951c16979 100644 --- 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 @@ -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 10bf97762..ef533fa81 100644 --- 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 diff --git a/gettext-tools/src/read-catalog.h b/gettext-tools/src/read-catalog.h index 97358dc94..4b0dbd2c6 100644 --- 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 . @@ -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; -- 2.47.3