svn commit: r1665438 - /subversion/trunk/subversion/include/svn_repos.h

[st...@apache.org]

Author: stefan2
Date: Tue Mar 10 10:10:46 2015
New Revision: 1665438

URL: http://svn.apache.org/r1665438
Log:
Correct and complete docstrings in the Repos layer API after 1.9 review.
No functional change.

* subversion/include/svn_repos.h
  (svn_repos_capabilities): Explicitly document the hash key type.  Remove
                            '()' from function names in the @see line.
                            Document pool usage.
  (svn_repos_fs_type): Add reference to the list of built-in types. 
  (svn_repos_hotcopy3): BDB is the only backend not sending notifications.
                        Document CANCEL_FUNC.
  (svn_repos_get_commit_editor5): NULL is an identifier.
  (svn_repos_get_file_revs2): Use slightly clearer wording.
  (svn_repos_fs_lock_many,
   svn_repos_fs_unlock_many: Add reference to the FS API func that provides
                             more detail. 
  (svn_repos_info_format): Refer to latest FS API function.  Document pool
                           usage.  Remove '()' from function names in @see.

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

Modified: subversion/trunk/subversion/include/svn_repos.h
URL: http://svn.apache.org/viewvc/subversion/trunk/subversion/include/svn_repos.h?rev=1665438&r1=1665437&r2=1665438&view=diff
==============================================================================
--- subversion/trunk/subversion/include/svn_repos.h (original)
+++ subversion/trunk/subversion/include/svn_repos.h Tue Mar 10 10:10:46 2015
@@ -559,15 +559,18 @@ svn_repos_has_capability(svn_repos_t *re
                          apr_pool_t *pool);
 
 /**
- * Return a set capabilities supported by the running Subversion library and by
- * @a repos.  (Capabilities supported by this version of Subversion but not by
- * @a repos are not listed.  This may happen when svn_repos_upgrade2() has not
- * been called after a software upgrade.)
+ * Return a set of @a capabilities supported by the running Subversion
+ * library and by @a repos.  (Capabilities supported by this version of
+ * Subversion but not by @a repos are not listed.  This may happen when
+ * svn_repos_upgrade2() has not been called after a software upgrade.)
  *
- * The set is represented as a hash whose keys are the set members.  The values
- * are not defined.
+ * The set is represented as a hash whose const char * keys are the set
+ * members.  The values are not defined.
  *
- * @see svn_repos_info_format()
+ * Allocate @a capabilities in @a result_pool and use @a scratch_pool for
+ * temporary allocations.
+ *
+ * @see svn_repos_info_format
  *
  * @since New in 1.9.
  */
@@ -628,6 +631,8 @@ svn_repos_fs(svn_repos_t *repos);
 /** Return the type of filesystem associated with repository object
  * @a repos allocated in @a pool.
  *
+ * @see #svn_fs_backend_names
+ *
  * @since New in 1.9.
  */
 const char *
@@ -650,10 +655,14 @@ svn_repos_fs_type(svn_repos_t *repos, ap
  * called with the @a notify_baton and a notification structure containing
  * appropriate values in @c start_revision and @c end_revision (both
  * inclusive). @c start_revision might be equal to @c end_revision in
- * case the copied range consists of a single revision. Currently, this
- * notification is only supported for FSFS repositories. @a notify_func
+ * case the copied range consists of a single revision.  Currently, this
+ * notification is not triggered by the BDB backend. @a notify_func
  * may be @c NULL if this notification is not required.
  *
+ * The optional @a cancel_func callback will be invoked with
+ * @a cancel_baton as usual to allow the user to preempt this potentially
+ * lengthy operation.
+ *
  * @since New in 1.9.
  */
 svn_error_t *
@@ -1523,19 +1532,19 @@ svn_repos_replay(svn_fs_root_t *root,
  * after the commit has succeeded) @c close_edit will invoke
  * @a commit_callback with a filled-in #svn_commit_info_t *, @a commit_baton,
  * and @a pool or some subpool thereof as arguments.  The @c repos_root field
- * of the #svn_commit_info_t is null.  If @a commit_callback
+ * of the #svn_commit_info_t is @c NULL.  If @a commit_callback
  * returns an error, that error will be returned from @c close_edit,
  * otherwise if there was a post-commit hook failure, then that error
  * will be returned with code SVN_ERR_REPOS_POST_COMMIT_HOOK_FAILED.
- * (Note that prior to Subversion 1.6, @a commit_callback cannot be NULL; if
- * you don't need a callback, pass a dummy function.)
+ * (Note that prior to Subversion 1.6, @a commit_callback cannot be @c NULL;
+ * if you don't need a callback, pass a dummy function.)
  *
  * Calling @a (*editor)->abort_edit aborts the commit, and will also
  * abort the commit transaction unless @a txn was supplied (not @c
  * NULL).  Callers who supply their own transactions are responsible
  * for cleaning them up (either by committing them, or aborting them).
  *
- * @since New in 1.5. Since 1.6, @a commit_callback can be null.
+ * @since New in 1.5. Since 1.6, @a commit_callback can be @c NULL.
  *
  * @note Yes, @a repos_url_decoded is a <em>decoded</em> URL.  We realize
  * that's sorta wonky.  Sorry about that.
@@ -2083,7 +2092,7 @@ svn_repos_fs_get_mergeinfo(svn_mergeinfo
  * the revision range for @a include_merged_revision @c FALSE reporting by
  * switching @a start with @a end.
  *
- * @note Prior to Subversion 1.9, this function may accept delta handlers
+ * @note Prior to Subversion 1.9, this function may request delta handlers
  * from @a handler even for empty text deltas.  Starting with 1.9, the
  * delta handler / baton return arguments passed to @a handler will be
  * #NULL unless there is an actual difference in the file contents between
@@ -2269,6 +2278,8 @@ svn_repos_fs_begin_txn_for_update(svn_fs
  * The lock and path passed to @a lock_callback will be allocated in
  * @a result_pool.  Use @a scratch_pool for temporary allocations.
  *
+ * @see svn_fs_lock_many
+ *
  * @since New in 1.9.
  */
 svn_error_t *
@@ -2321,6 +2332,8 @@ svn_repos_fs_lock(svn_lock_t **lock,
  * The path passed to @a lock_callback will be allocated in @a result_pool.
  * Use @a scratch_pool for temporary allocations.
  *
+ * @see svn_fs_unlock_many
+ *
  * @since New in 1.9.
  */
 svn_error_t *
@@ -2702,12 +2715,13 @@ svn_repos_node_from_baton(void *edit_bat
  *
  * Set @a *repos_format to the repository format number of @a repos, which is
  * an integer that increases when incompatible changes are made (such as
- * by #svn_repos_upgrade).
+ * by #svn_repos_upgrade2).
  *
- * Set @a *supports_version to the version number of the minimum Subversion GA
- * release that can read and write @a repos.
+ * Set @a *supports_version to the version number of the minimum Subversion
+ * GA release that can read and write @a repos; allocate it in
+ * @a result_pool.  Use @a scratch_pool for temporary allocations.
  *
- * @see svn_fs_info_format(), svn_repos_capabilities()
+ * @see svn_fs_info_format, svn_repos_capabilities
  *
  * @since New in 1.9.
  */