svn commit: r987939 - in /subversion/trunk/subversion/libsvn_ra_neon: ra_neon.h util.c

[da...@apache.org]

Author: danielsh
Date: Sun Aug 22 18:28:30 2010
New Revision: 987939

URL: http://svn.apache.org/viewvc?rev=987939&view=rev
Log:
Document internal ra_neon XML parsing APIs.

Review by: julianfoad
(earlier version)

* subversion/libsvn_ra_neon/util.c
  (multistatus_elements, multistatus_nesting_table, validate_element):
    Add derived-from-implementation docstrings.

* subversion/libsvn_ra_neon/ra_neon.h
  (svn_ra_neon__xml_elmid, anonymous enum ELEM_*):
    Note that these two may be related.

Modified:
    subversion/trunk/subversion/libsvn_ra_neon/ra_neon.h
    subversion/trunk/subversion/libsvn_ra_neon/util.c

Modified: subversion/trunk/subversion/libsvn_ra_neon/ra_neon.h
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/libsvn_ra_neon/ra_neon.h?rev=987939&r1=987938&r2=987939&view=diff
==============================================================================
--- subversion/trunk/subversion/libsvn_ra_neon/ra_neon.h (original)
+++ subversion/trunk/subversion/libsvn_ra_neon/ra_neon.h Sun Aug 22 18:28:30 2010
@@ -57,6 +57,7 @@ extern "C" {
 #define SVN_RA_NEON__XML_CDATA   (1<<1)
 #define SVN_RA_NEON__XML_COLLECT ((1<<2) | SVN_RA_NEON__XML_CDATA)
 
+/* ### Related to anonymous enum below? */
 typedef int svn_ra_neon__xml_elmid;
 
 /** XML element */
@@ -739,6 +740,7 @@ svn_ra_neon__check_parse_error(const cha
                                ne_xml_parser *xml_parser,
                                const char *url);
 
+/* ### Related to svn_ra_neon__xml_elmid? */
 /* ### add SVN_RA_NEON_ to these to prefix conflicts with (sys) headers? */
 enum {
   /* Redefine Neon elements */

Modified: subversion/trunk/subversion/libsvn_ra_neon/util.c
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/libsvn_ra_neon/util.c?rev=987939&r1=987938&r2=987939&view=diff
==============================================================================
--- subversion/trunk/subversion/libsvn_ra_neon/util.c (original)
+++ subversion/trunk/subversion/libsvn_ra_neon/util.c Sun Aug 22 18:28:30 2010
@@ -82,6 +82,7 @@ xml_parser_create(svn_ra_neon__request_t
  * for our custom error parser - could use the ne_basic.h interfaces.
  */
 
+/* List of XML elements expected in 207 Multi-Status responses. */
 static const svn_ra_neon__xml_elm_t multistatus_elements[] =
   { { "DAV:", "multistatus", ELEM_multistatus, 0 },
     { "DAV:", "response", ELEM_response, 0 },
@@ -99,6 +100,21 @@ static const svn_ra_neon__xml_elm_t mult
   };
 
 
+/* Sparse matrix listing the permitted child elements of each element.
+
+   The permitted direct children of the element named in the first column are
+   the elements named in the remainder of the row.
+
+   There may be any number of rows, and any number of columns in each row; any
+   non-positive value (such as SVN_RA_NEON__XML_INVALID) serves as a sentinel.
+
+   The last element in a row is returned if the head-of-row element is found
+   with a child that's not listed in the remainder of the row.  The singleton
+   element of the last (sentinel) row is returned if a tag-with-children is
+   found that isn't the head of any row.
+
+   See validate_element().
+ */
 static const int multistatus_nesting_table[][5] =
   { { ELEM_root, ELEM_multistatus, SVN_RA_NEON__XML_INVALID },
     { ELEM_multistatus, ELEM_response, ELEM_responsedescription,
@@ -115,6 +131,11 @@ static const int multistatus_nesting_tab
   };
 
 
+/* PARENT and CHILD are enum values of ELEM_* type.
+   Return a positive integer if CHILD is a valid direct child of PARENT, and
+   a negative integer (SVN_RA_NEON__XML_INVALID or SVN_RA_NEON__XML_DECLINE,
+   at the moment) otherwise.
+ */
 static int
 validate_element(int parent, int child)
 {