svn commit: r1670149 - in /subversion/trunk/subversion/include: svn_fs.h svn_repos.h

[ph...@apache.org]

Author: philip
Date: Mon Mar 30 17:28:42 2015
New Revision: 1670149

URL: http://svn.apache.org/r1670149
Log:
Documentation points raised by API review, no code changes.

* subversion/include/svn_fs.h
  (svn_fs_lock_target_create,
   svn_fs_lock_many, svn_fs_unlock_many): Tweak docstring.

* subversion/include/svn_fs.h
  (svn_repos_fs_lock_many, svn_repos_fs_unlock_many): Tweak docstring.

Modified:
    subversion/trunk/subversion/include/svn_fs.h
    subversion/trunk/subversion/include/svn_repos.h

Modified: subversion/trunk/subversion/include/svn_fs.h
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/include/svn_fs.h?rev=1670149&r1=1670148&r2=1670149&view=diff
==============================================================================
--- subversion/trunk/subversion/include/svn_fs.h (original)
+++ subversion/trunk/subversion/include/svn_fs.h Mon Mar 30 17:28:42 2015
@@ -2682,7 +2682,12 @@ void svn_fs_lock_target_set_token(svn_fs
  * returns, use svn_error_dup() to preserve the error.
  *
  * If the callback returns an error no further callbacks will be made
- * and svn_fs_lock_many/svn_fs_unlock_many will return an error.
+ * and svn_fs_lock_many/svn_fs_unlock_many will return an error.  The
+ * caller cannot rely on any particular order for these callbacks and
+ * cannot rely on interrupting the underlying operation by returning
+ * an error.  Returning an error stops the callbacks but any locks
+ * that would have been reported in further callbacks may, or may not,
+ * still be created/released.
  *
  * @since New in 1.9.
  */
@@ -2730,7 +2735,8 @@ typedef svn_error_t *(*svn_fs_lock_callb
  *
  * For each path in @a lock_targets @a lock_callback will be invoked
  * passing @a lock_baton and the lock and error that apply to path.
- * @a lock_callback can be NULL in which case it is not called.
+ * @a lock_callback can be NULL in which case it is not called and any
+ * errors that would have been passed to the callback are not reported.
  *
  * The lock and path passed to @a lock_callback will be allocated in
  * @a result_pool.  Use @a scratch_pool for temporary allocations.
@@ -2804,7 +2810,8 @@ svn_fs_generate_lock_token(const char **
  * For each path in @a unlock_targets @a lock_callback will be invoked
  * passing @a lock_baton and error that apply to path.  The @a lock
  * passed to the callback will be NULL.  @a lock_callback can be NULL
- * in which case it is not called.
+ * in which case it is not called and any errors that would have been
+ * passed to the callback are not reported.
  *
  * The path passed to lock_callback will be allocated in @a result_pool.
  * Use @a scratch_pool for temporary allocations.

Modified: subversion/trunk/subversion/include/svn_repos.h
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/include/svn_repos.h?rev=1670149&r1=1670148&r2=1670149&view=diff
==============================================================================
--- subversion/trunk/subversion/include/svn_repos.h (original)
+++ subversion/trunk/subversion/include/svn_repos.h Mon Mar 30 17:28:42 2015
@@ -2268,7 +2268,8 @@ svn_repos_fs_begin_txn_for_update(svn_fs
  *
  * For each path in @a targets @a lock_callback will be invoked
  * passing @a lock_baton and the lock and error that apply to path.
- * @a lock_callback can be NULL in which case it is not called.
+ * @a lock_callback can be NULL in which case it is not called and any
+ * errors that would have been passed to the callback are not reported.
  *
  * If an error occurs when running the post-lock hook the error is
  * returned wrapped with #SVN_ERR_REPOS_POST_LOCK_HOOK_FAILED.  If the
@@ -2325,7 +2326,8 @@ svn_repos_fs_lock(svn_lock_t **lock,
  * For each path in @a targets @a lock_callback will be invoked
  * passing @a lock_baton and error that apply to path.  The lock
  * passed to the callback will be NULL.  @a lock_callback can be NULL
- * in which case it is not called.
+ * in which case it is not called and any errors that would have been
+ * passed to the callback are not reported.
  *
  * If an error occurs when running the post-unlock hook, return the
  * original error wrapped with #SVN_ERR_REPOS_POST_UNLOCK_HOOK_FAILED.