xlocator, its: Add more comments

diff --git a/gettext-tools/src/its.c b/gettext-tools/src/its.c
index 743ea82c0d59283cc0e07c9574c5d36dbb96a870..09d10fc0882fcea6c32054a084e1e65956b48948 100644 (file)
--- a/gettext-tools/src/its.c
+++ b/gettext-tools/src/its.c
@@ -38,16 +38,23 @@
 
 #define _(str) gettext (str)
 
-/* The Internationalization Tag Set (ITS) 2.0 standard is published at:
+/* The Internationalization Tag Set (ITS) 2.0 standard is available at:
    http://www.w3.org/TR/its20/
 
    This implementation supports only a few data categories, useful for
    gettext-based projects.  Other data categories can be added by
-   extending a class from its_rule_class_ty and registering it in
+   extending the its_rule_class_ty class and registering it in
    init_classes().
 
-   The value associated with a data category is represented as an
-   array of key-value pairs.  */
+   The message extraction is done in three phases.  In the first
+   phase, its_rule_list_apply() associates values to matching XML
+   elements in the target document.  In the second phase, it traverses
+   the tree and marks translatable elements.  In the final phase, it
+   extracts text contents from the marked elements.
+
+   The values associated with an XML node are represented as an array
+   of key-value pairs, where both keys and values are string.  The
+   values are stored in node->_private.  */
 
 #define ITS_NS "http://www.w3.org/2005/11/its"
 
@@ -507,6 +514,7 @@ its_localization_note_rule_constructor (struct its_rule_ty *pop, xmlNode *node)
       its_value_list_append (&pop->values, "locNotePointer", prop);
       free (prop);
     }
+  /* FIXME: locNoteRef and locNoteRefPointer */
 }
 
 struct its_value_list_ty *

diff --git a/gettext-tools/src/its.h b/gettext-tools/src/its.h
index ae2c04cb4646ee8edcfae72b777ccbdc3538c665..c9e5dec599f53a14bf0a1b03fb9877f240bf3fb7 100644 (file)
--- a/gettext-tools/src/its.h
+++ b/gettext-tools/src/its.h
@@ -28,13 +28,17 @@ extern "C" {
 
 typedef struct its_rule_list_ty its_rule_list_ty;
 
+/* Creates a fresh its_rule_list_ty holding global ITS rules.  */
 extern its_rule_list_ty *its_rule_list_alloc (void);
 
+/* Releases memory allocated for RULES.  */
 extern void its_rule_list_free (its_rule_list_ty *rules);
 
+/* Loads global ITS rules from FILENAME.  */
 extern bool its_rule_list_add_file (its_rule_list_ty *rules,
                                     const char *filename);
 
+/* Extracts messages from FP, accoding to the loaded ITS rules.  */
 extern void its_rule_list_extract (its_rule_list_ty *rules,
                                    FILE *fp, const char *real_filename,
                                    const char *logical_filename,

diff --git a/gettext-tools/src/xlocator.c b/gettext-tools/src/xlocator.c
index 664f040d28bced90dc230dbc2a27d5cb309f33b7..9afb448507efbe156183e48848615f20cb068ab9 100644 (file)
--- a/gettext-tools/src/xlocator.c
+++ b/gettext-tools/src/xlocator.c
@@ -169,6 +169,7 @@ xlocator_list_resolve_target (struct xlocator_list_ty *locators,
   char *target_uri = NULL;
   char *result = NULL;
 
+  /* FIXME: Implement transformURI (the case locators->is_transform).  */
   if (!target->is_indirection)
     target_uri = xstrdup (target->uri);
   else

diff --git a/gettext-tools/src/xlocator.h b/gettext-tools/src/xlocator.h
index 3c0f55bb9f4f61302fd9e981d5dc9c12de153452..3ef85d0682505c6c6e7cace60e4caec9b396bcff 100644 (file)
--- a/gettext-tools/src/xlocator.h
+++ b/gettext-tools/src/xlocator.h
@@ -27,11 +27,19 @@ extern "C" {
 
 typedef struct xlocator_list_ty xlocator_list_ty;
 
+/* Creates a fresh xlocator_list_ty with the base URI BASE, and loads
+   the locating rules from the files in DIRECTORY.  */
 extern struct xlocator_list_ty *xlocator_list_alloc (const char *base,
                                                      const char *directory);
+
+/* Determines the location of resource associated with PATH, accoding
+   to the loaded locating rules.  If INSPECT_CONTENT is true, it also
+   checks the content of the file pointed by PATH.  */
 extern char *xlocator_list_locate (xlocator_list_ty *locators,
                                    const char *path,
                                    bool inspect_content);
+
+/* Releases memory allocated for LOCATORS.  */
 extern void xlocator_list_free (xlocator_list_ty *locators);
 
 #ifdef __cplusplus