svn commit: r1423160 - /subversion/trunk/subversion/include/svn_wc.h

[ju...@apache.org]

Author: julianfoad
Date: Mon Dec 17 21:32:37 2012
New Revision: 1423160

URL: http://svn.apache.org/viewvc?rev=1423160&view=rev
Log:
* subversion/include/svn_wc.h
  (svn_wc_prop_set4,
   svn_wc_canonicalize_svn_prop): Major update to the doc strings.

Modified:
    subversion/trunk/subversion/include/svn_wc.h

Modified: subversion/trunk/subversion/include/svn_wc.h
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/include/svn_wc.h?rev=1423160&r1=1423159&r2=1423160&view=diff
==============================================================================
--- subversion/trunk/subversion/include/svn_wc.h (original)
+++ subversion/trunk/subversion/include/svn_wc.h Mon Dec 17 21:32:37 2012
@@ -6033,19 +6033,29 @@ svn_wc_prop_get(const svn_string_t **val
  * NULL, remove property @a name from @a local_abspath.  Use @a wc_ctx to
  * access @a local_abspath.
  *
- * If @a skip_checks is TRUE, do no validity checking.  But if @a
- * skip_checks is FALSE, and @a name is not a valid property for @a
- * path, return an error, either #SVN_ERR_ILLEGAL_TARGET (if the
+ * @a name may be a regular property or a "wc property".  If @a name is
+ * an "entry property", return the error #SVN_ERR_BAD_PROP_KIND (even if
+ * @a skip_checks is TRUE).
+ *
+ * If @a name is a "wc property", then just update the WC DAV cache for
+ * @a local_abspath with @a name and @a value.  In this case, @a depth
+ * must be #svn_depth_empty.
+ *
+ * The rest of this description applies when @a name is a regular property.
+ *
+ * If @a name is a name in the reserved "svn:" name space, and @a value is
+ * non-null, then canonicalize the property value and check the property
+ * name and value as documented for svn_wc_canonicalize_svn_prop().
+ * @a skip_checks controls the level of checking as documented there.
+ *
+ * Return an error if the canonicalization or the check fails.
+ * The error will be either #SVN_ERR_ILLEGAL_TARGET (if the
  * property is not appropriate for @a path), or
  * #SVN_ERR_BAD_MIME_TYPE (if @a name is "svn:mime-type", but @a value
  * is not a valid mime-type).
+ * ### That is not currently right -- several other errors can be raised.
  *
- * @a depth follows the usual semeatic for depth.  If the property is a
- * wc property, @a depth must be #svn_depth_empty.
- *
- * @a name may be a wc property or a regular property; but if it is an
- * entry property, return the error #SVN_ERR_BAD_PROP_KIND, even if
- * @a skip_checks is TRUE.
+ * @a depth follows the usual semantics for depth.
  *
  * @a changelist_filter is an array of <tt>const char *</tt> changelist
  * names, used as a restrictive filter on items whose properties are
@@ -6063,6 +6073,14 @@ svn_wc_prop_get(const svn_string_t **val
  *
  * Use @a scratch_pool for temporary allocation.
  *
+ * @note If the caller is setting both svn:mime-type and svn:eol-style in
+ * separate calls, and @a skip_checks is false, there is an ordering
+ * dependency between them, as the validity check for svn:eol-style makes
+ * use of the current value of svn:mime-type.
+ *
+ * ### The error code on validity check failure should be specified, and
+ *     should be a single code or a very small set of possibilities.
+ *
  * @since New in 1.7.
  */
 svn_error_t *
@@ -6081,7 +6099,7 @@ svn_wc_prop_set4(svn_wc_context_t *wc_ct
 
 /** Similar to svn_wc_prop_set4(), but with a #svn_wc_adm_access_t /
  * relative path parameter pair, no @a depth parameter, no changelist
- * filtering (for the depth-based property setting), and no cancelation.
+ * filtering (for the depth-based property setting), and no cancellation.
  *
  * @since New in 1.6.
  * @deprecated Provided for backwards compatibility with the 1.6 API.
@@ -6182,21 +6200,55 @@ typedef svn_error_t *(*svn_wc_canonicali
  * is otherwise invalid, throw an error.  Otherwise, set @a *propval_p
  * to a canonicalized version of the property value.
  *
- * If @a skip_some_checks is TRUE, some validity checks and
- * canonicalizations are skipped. Presently, these are:
- *   - For svn:eol-style: strip white space; check value is recognized;
- *       check file content matches value.
- *   - For svn:mime-type: strip white space; check value has reasonable
- *       syntax.
- *
- * Some validity checks require access to the contents and MIME type
- * of the target if it is a file; they will call @a prop_getter with @a
- * getter_baton, which then needs to set the MIME type and print the
- * contents of the file to the given stream.
+ * The exact set of canonicalizations and checks may vary across different
+ * versions of this API.  Currently:
+ *
+ *   - svn:executable
+ *   - svn:needs-lock
+ *   - svn:special
+ *     - set the value to '*'
+ *
+ *   - svn:keywords
+ *     - strip leading and trailing white space
+ *
+ *   - svn:ignore
+ *   - svn:global-ignores
+ *   - svn:auto-props
+ *     - add a final a newline character if missing
+ *
+ *   - svn:externals
+ *     - add a final a newline character if missing
+ *     - check for valid syntax
+ *     - check for no duplicate entries
+ *
+ *   - svn:mergeinfo
+ *     - canonicalize
+ *     - check for validity
+ *
+ * Also, unless @a skip_some_checks is TRUE:
+ *
+ *   - svn:eol-style
+ *     - strip leading and trailing white space
+ *     - check value is recognized
+ *     - check file content has a self-consistent EOL style
+ *       (but not necessarily that it matches @a propval)
+ *
+ *   - svn:mime-type
+ *     - strip white space
+ *     - check for reasonable syntax
+ *
+ * The EOL-style check (if not skipped) requires access to the contents and
+ * MIME type of the target if it is a file.  It will call @a prop_getter with
+ * @a getter_baton.  The callback must set the MIME type and/or write the
+ * contents of the file to the given stream.  If @a skip_some_checks is true,
+ * then @a prop_getter is not used and may be NULL.
  *
  * @a path should be the path of the file in question; it is only used
  * for error messages.
  *
+ * ### The error code on validity check failure should be specified, and
+ *     should be a single code or a very small set of possibilities.
+ *
  * ### This is not actually related to the WC, but it does need to call
  * ### svn_wc_parse_externals_description3.
  *