For review, please. The patch below aims to provide complete doc
strings for (the existing implementation of) the WC-NG properties API.
I assume "properties" refers to regular, versioned properties
throughout.
I checked the implementation with regard to returning an error when the
node is not found.
I believe svn_wc__db_base_get_props() is meant to return an empty
(non-NULL) hash to represent "no properties", both because that's
consistent with the input and outputs of the rest of these functions and
because the rest of these functions never write "null" to the
"properties" column of the BASE table when writing an empty set of
properties. The non-nullness of that SQL column is not (yet) documented
so I am not certain that there are no other functions that could write
"null".
[[[
Provide complete doc strings for the WC-NG properties-storage API.
* subversion/libsvn_wc/wc_db.h
(svn_wc__db_base_get_prop, svn_wc__db_base_get_props,
svn_wc__db_op_set_props, svn_wc__db_temp_op_set_pristine_props,
svn_wc__db_read_prop, svn_wc__db_read_props,
svn_wc__db_read_pristine_props): Re-write doc strings.
--This line, and those below, will be ignored--
Index: subversion/libsvn_wc/wc_db.h
===================================================================
--- subversion/libsvn_wc/wc_db.h (revision 917441)
+++ subversion/libsvn_wc/wc_db.h (working copy)
@@ -646,14 +646,12 @@ svn_wc__db_base_get_info(svn_wc__db_stat
apr_pool_t *scratch_pool);
-/** Return a property's value from a node in the BASE tree.
+/** Set *PROPVAL to the value of the property named PROPNAME of the node
+ * LOCAL_ABSPATH in the BASE tree.
*
- * This is a convenience function to return a single property from the
- * BASE tree node indicated by LOCAL_ABSPATH. The property's name is
- * given in PROPNAME, and the value returned in PROPVAL.
- *
- * All returned data will be allocated in RESULT_POOL. All temporary
- * allocations will be made in SCRATCH_POOL.
+ * If the node has no property named PROPNAME, set *PROPVAL to NULL.
+ * If the node is not found in the BASE tree, return an error.
+ * Allocate *PROPVAL in RESULT_POOL.
*/
svn_error_t *
svn_wc__db_base_get_prop(const svn_string_t **propval,
@@ -664,14 +662,12 @@ svn_wc__db_base_get_prop(const svn_strin
apr_pool_t *scratch_pool);
-/** Return all properties of the given BASE tree node.
+/** Set *PROPS to the properties of the node LOCAL_ABSPATH in the BASE tree.
*
- * All of the properties for the node indicated by LOCAL_ABSPATH will be
- * returned in PROPS as a mapping of const char * names to
- * const svn_string_t * values.
- *
- * All returned data will be allocated in RESULT_POOL. All temporary
- * allocations will be made in SCRATCH_POOL.
+ * *PROPS maps "const char *" names to "const svn_string_t *" values.
+ * If the node has no properties, set *PROPS to an empty hash.
+ * If the node is not found in the BASE tree, return an error.
+ * Allocate *PROPS and its keys and values in RESULT_POOL.
*/
svn_error_t *
svn_wc__db_base_get_props(apr_hash_t **props,
@@ -952,21 +948,31 @@ svn_wc__db_op_add_symlink(svn_wc__db_t *
apr_pool_t *scratch_pool);
-/* ### note: there is no db_op_set_prop() function. callers must read
- ### all the properties, change one, and write all the properties. */
-
-/* Set the props on the ACTUAL node for LOCAL_ABSPATH to PROPS. This will
- overwrite whatever working props the node currently has. PROPS maps
- property names of type "const char *" to values of type
- "const svn_string_t *". Use SCRATCH_POOL for temporary allocations. */
+/** Set the properties of the node LOCAL_ABSPATH in the ACTUAL tree to
+ * PROPS.
+ *
+ * This will overwrite whatever working properties the node currently has.
+ * Create an entry in the ACTUAL tree for the node if it is not there.
+ * PROPS maps "const char *" names to "const svn_string_t *" values.
+ * To specify no properties, PROPS must be an empty hash, not NULL.
+ *
+ * @note: There is no db_op_set_prop() function. Callers must read
+ * all the properties, change one, and write all the properties.
+ */
svn_error_t *
svn_wc__db_op_set_props(svn_wc__db_t *db,
const char *local_abspath,
apr_hash_t *props,
apr_pool_t *scratch_pool);
-/* Sets the pristine props of LOCAL_ABSPATH on BASE, or when ON_WORKING is
- TRUE on WORKING */
+/** Set the properties of the node LOCAL_ABSPATH in the BASE tree (if
+ * ON_WORKING is FALSE) or in the WORKING tree (if ON_WORKING is TRUE) to
+ * PROPS.
+ *
+ * PROPS maps "const char *" names to "const svn_string_t *" values.
+ * To specify no properties, PROPS must be an empty hash, not NULL.
+ * If the node is not found in the specified tree, return an error.
+ */
svn_error_t *
svn_wc__db_temp_op_set_pristine_props(svn_wc__db_t *db,
const char *local_abspath,
@@ -1268,12 +1274,13 @@ svn_wc__db_read_info(svn_wc__db_status_t
apr_pool_t *scratch_pool);
-/** Return a property's value for a node, first using ACTUAL, then
- * WORKING, then BASE. The property's name is given in PROPNAME, and
- * the value returned in PROPVAL.
- *
- * All returned data will be allocated in RESULT_POOL. All temporary
- * allocations will be made in SCRATCH_POOL.
+/** Set *PROPVAL to the value of the property named PROPNAME of the node
+ * LOCAL_ABSPATH in the ACTUAL tree if the node is found there, else in the
+ * WORKING tree, else in the BASE tree.
+ *
+ * If the node has no property named PROPNAME, set *PROPVAL to NULL.
+ * If the node is not found in any tree, return an error.
+ * Allocate *PROPVAL in RESULT_POOL.
*/
svn_error_t *
svn_wc__db_read_prop(const svn_string_t **propval,
@@ -1284,13 +1291,15 @@ svn_wc__db_read_prop(const svn_string_t
apr_pool_t *scratch_pool);
-/* Read into PROPS the properties for LOCAL_ABSPATH in DB. This first check
- the ACTUAL node, then the WORKING node, and finally the BASE node for
- properties. PROPS maps property names of type "const char *" to values
- of type "const svn_string_t *".
-
- Allocate PROPS in RESULT_POOL and do temporary allocations
- in SCRATCH_POOL. */
+/** Set *PROPS to the properties of the node LOCAL_ABSPATH in the ACTUAL
+ * tree if the node is found there, else in the WORKING tree, else in the
+ * BASE tree.
+ *
+ * PROPS maps "const char *" names to "const svn_string_t *" values.
+ * If the node has no properties, set *PROPS to an empty hash.
+ * If the node is not found in any tree, return an error.
+ * Allocate *PROPS and its keys and values in RESULT_POOL.
+ */
svn_error_t *
svn_wc__db_read_props(apr_hash_t **props,
svn_wc__db_t *db,
@@ -1299,13 +1308,14 @@ svn_wc__db_read_props(apr_hash_t **props
apr_pool_t *scratch_pool);
-/* Read into PROPS the properties for LOCAL_ABSPATH in DB. This first check
- the WORKING node, and then the BASE node for properties. PROPS maps
- property names of type "const char *" to values of type
- "const svn_string_t *".
-
- Allocate PROPS in RESULT_POOL and do temporary allocations
- in SCRATCH_POOL. */
+/** Set *PROPS to the properties of the node LOCAL_ABSPATH in the WORKING
+ * tree if the node is found there, else in the BASE tree.
+ *
+ * *PROPS maps "const char *" names to "const svn_string_t *" values.
+ * If the node has no properties, set *PROPS to an empty hash.
+ * If the node is not found in either tree, return an error.
+ * Allocate *PROPS and its keys and values in RESULT_POOL.
+ */
svn_error_t *
svn_wc__db_read_pristine_props(apr_hash_t **props,
svn_wc__db_t *db,
]]]
- Julian
Received on 2010-03-01 13:24:20 CET