Author: stefan2
Date: Tue Mar 10 10:10:30 2015
New Revision: 1665437
URL: http://svn.apache.org/r1665437
Log:
Correct and complete docstrings in the FS API after 1.9 review.
No functional change.
* subversion/include/svn_fs.h
(svn_fs_backend_names): New Doxygen group allowing us to refer to the
pre-defined set of backends. Move to front due
to issues with group nesting.
(SVN_FS_CONFIG_COMPATIBLE_VERSION): Works for the current release as well.
(svn_fs_open2): Correct cleanup behavior description for RESULT_POOL.
Document SCRATCH_POOL.
(svn_fs_upgrade_notify_t): Grammar fix.
(svn_fs_upgrade2): Refer to latest repos API.
(svn_fs_hotcopy3): BDB is the only backend not sending notifications.
Document CANCEL_FUNC.
(svn_fs_compare_ids,
svn_fs_check_related): "Now" is 1.9.
(svn_fs_props_changed): Fix confusing wording.
(svn_fs_info_format,
svn_fs_lock_target_t): For clarity, remove '()' from function names in
@see line.
(svn_fs_fsfs_info_t): Make comment visible to doxygen.
(svn_fs_info_placeholder_t): For clarity, remove '()' from function names
in @see line.
(svn_fs_info): Mention FSX alongside FSFS.
(svn_fs_info_dup): Update pool usage documentation.
Modified:
subversion/trunk/subversion/include/svn_fs.h
Modified: subversion/trunk/subversion/include/svn_fs.h
URL:
http://svn.apache.org/viewvc/subversion/trunk/subversion/include/svn_fs.h?rev=1665437&r1=1665436&r2=1665437&view=diff
==============================================================================
--- subversion/trunk/subversion/include/svn_fs.h (original)
+++ subversion/trunk/subversion/include/svn_fs.h Tue Mar 10 10:10:30 2015
@@ -65,6 +65,30 @@ svn_fs_version(void);
/** An object representing a Subversion filesystem. */
typedef struct svn_fs_t svn_fs_t;
+/**
+ * @defgroup svn_fs_backend_names Built-in back-ends
+ * Constants defining the currently supported built-in filesystem backends.
+ *
+ * @see svn_fs_type
+ * @{
+ */
+/** @since New in 1.1. */
+#define SVN_FS_TYPE_BDB "bdb"
+/** @since New in 1.1. */
+#define SVN_FS_TYPE_FSFS "fsfs"
+
+/**
+ * EXPERIMENTAL filesystem backend.
+ *
+ * It is not ready for general production use. Please consult the
+ * respective release notes on suggested usage scenarios.
+ *
+ * @since New in 1.9.
+ */
+#define SVN_FS_TYPE_FSX "fsx"
+
+/** @} */
+
/**
* @name Filesystem configuration options
@@ -139,23 +163,10 @@ typedef struct svn_fs_t svn_fs_t;
/* Note to maintainers: if you add further SVN_FS_CONFIG_FSFS_CACHE_* knobs,
update fs_fs.c:verify_as_revision_before_current_plus_plus(). */
-/* See also svn_fs_type(). */
-/** @since New in 1.1. */
-#define SVN_FS_CONFIG_FS_TYPE "fs-type"
-/** @since New in 1.1. */
-#define SVN_FS_TYPE_BDB "bdb"
-/** @since New in 1.1. */
-#define SVN_FS_TYPE_FSFS "fsfs"
-
-/**
- * EXPERIMENTAL filesystem backend.
+/** Select the filesystem type. See also #svn_fs_type().
*
- * It is not ready for general production use. Please consult the
- * respective release notes on suggested usage scenarios.
- *
- * @since New in 1.9.
- */
-#define SVN_FS_TYPE_FSX "fsx"
+ * @since New in 1.1. */
+#define SVN_FS_CONFIG_FS_TYPE "fs-type"
/** Create repository format compatible with Subversion versions
* earlier than 1.4.
@@ -185,9 +196,9 @@ typedef struct svn_fs_t svn_fs_t;
*/
#define SVN_FS_CONFIG_PRE_1_8_COMPATIBLE "pre-1.8-compatible"
-/** Create repository format compatible with Subversion versions
- * earlier than 1.9. The value must be a version in the same format
- * as #SVN_VER_NUMBER.
+/** Create repository format compatible with the specified Subversion
+ * release. The value must be a version in the same format as
+ * #SVN_VER_NUMBER and cannot exceed the current version.
*
* @note The @c patch component would often be ignored, due to our forward
* compatibility promises within minor release lines. It should therefore
@@ -291,8 +302,9 @@ svn_fs_create(svn_fs_t **fs_p,
* return a pointer to it in @a *fs_p. If @a fs_config is not @c
* NULL, the options it contains modify the behavior of the
* filesystem. The interpretation of @a fs_config is specific to the
- * filesystem back-end. The opened filesystem may be closed by
- * destroying @a result_pool.
+ * filesystem back-end. The opened filesystem will be allocated in
+ * @a result_pool may be closed by clearing or destroying that pool.
+ * Use @a scratch_pool for temporary allocations.
*
* @note The lifetime of @a fs_config must not be shorter than @a
* result_pool's. It's a good idea to allocate @a fs_config from
@@ -346,7 +358,7 @@ typedef enum svn_fs_upgrade_notify_actio
svn_fs_upgrade_format_bumped
} svn_fs_upgrade_notify_action_t;
-/** The type of a upgrade notification function. @a number is specifc
+/** The type of an upgrade notification function. @a number is specifc
* to @a action (see #svn_fs_upgrade_notify_action_t); @a action is the
* type of action being performed. @a baton is the corresponding baton
* for the notification function, and @a pool can be used for temporary
@@ -374,7 +386,7 @@ typedef svn_error_t *(*svn_fs_upgrade_no
* the user to preempt this potentially lengthy operation.
*
* @note You probably don't want to use this directly. Take a look at
- * svn_repos_upgrade() instead.
+ * svn_repos_upgrade2() instead.
*
* @note Canceling an upgrade is legal but may leave remnants of previous
* format data that may not be cleaned up automatically by later calls.
@@ -497,9 +509,13 @@ typedef void (*svn_fs_hotcopy_notify_t)(
* For each revision range copied, @a notify_func will be called with
* staring and ending revision numbers (both inclusive and not necessarily
* different) and with the @a notify_baton. Currently, this notification
- * is only supported in the FSFS backend. @a notify_func may be @c NULL
+ * 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.
+ *
* Use @a scratch_pool for temporary allocations.
*
* @since New in 1.9.
@@ -904,9 +920,9 @@ typedef struct svn_fs_id_t svn_fs_id_t;
/** Return -1, 0, or 1 if node revisions @a a and @a b are respectively
* unrelated, equivalent, or otherwise related (part of the same node).
*
- * @note Using FS ID based functions is now discouraged and may be fully
- * deprecated in future releases. New code should use #svn_fs_node_relation()
- * and #svn_fs_node_relation_t instead.
+ * @note Using FS ID based functions is discouraged since 1.9 and may be
+ * fully deprecated in future releases. New code should use
+ * #svn_fs_node_relation() and #svn_fs_node_relation_t instead.
*/
int
svn_fs_compare_ids(const svn_fs_id_t *a,
@@ -917,9 +933,9 @@ svn_fs_compare_ids(const svn_fs_id_t *a,
/** Return TRUE if node revisions @a id1 and @a id2 are related (part of the
* same node), else return FALSE.
*
- * @note Using FS ID based functions is now discouraged and may be fully
- * deprecated in future releases. New code should use #svn_fs_node_relation()
- * and #svn_fs_node_relation_t instead.
+ * @note Using FS ID based functions is discouraged since 1.9 and may be
+ * fully deprecated in future releases. New code should use
+ * #svn_fs_node_relation() and #svn_fs_node_relation_t instead.
*/
svn_boolean_t
svn_fs_check_related(const svn_fs_id_t *id1,
@@ -1847,7 +1863,7 @@ svn_fs_props_different(svn_boolean_t *di
* at all.
*
* @note Prior to Subversion 1.9, this function would return false negatives
- * as well for FSFS: If @a root1 and @a root2 were both transaction roots
+ * for FSFS: If @a root1 and @a root2 were both transaction roots
* and the proplists of both paths had been changed in their respective
* transactions, @a changed_p would be set to #FALSE.
*/
@@ -2434,7 +2450,7 @@ svn_fs_youngest_rev(svn_revnum_t *younge
* Set @a *supports_version to the version number of the minimum Subversion GA
* release that can read and write @a fs.
*
- * @see svn_repos_info_format()
+ * @see svn_repos_info_format
*
* @since New in 1.9.
*/
@@ -2615,7 +2631,7 @@ svn_fs_set_uuid(svn_fs_t *fs,
/** Lock information for use with svn_fs_lock_many() [and svn_repos_fs_...].
*
- * @see svn_fs_lock_target_create().
+ * @see svn_fs_lock_target_create
*
* @since New in 1.9.
*/
@@ -3045,7 +3061,7 @@ typedef struct svn_fs_fsfs_info_t {
* @note Zero (0) if (but not iff) the format does not support packing. */
svn_revnum_t min_unpacked_rev;
- /* TRUE if logical addressing is enabled for this repository.
+ /** TRUE if logical addressing is enabled for this repository.
* FALSE if repository uses physical addressing. */
svn_boolean_t log_addressing;
/* ### TODO: information about fsfs.conf? rep-cache.db? write locks? */
@@ -3080,10 +3096,10 @@ typedef struct svn_fs_fsx_info_t {
} svn_fs_fsx_info_t;
-/** @see svn_fs_info()
+/** @see svn_fs_info
* @since New in 1.9. */
typedef struct svn_fs_info_placeholder_t {
- /** @see svn_fs_type() */
+ /** @see svn_fs_type */
const char *fs_type;
/* Do not add new fields here, to maintain compatibility with the first
@@ -3093,10 +3109,11 @@ typedef struct svn_fs_info_placeholder_t
/**
* Set @a *fs_info to a struct describing @a fs. The type of the
* struct depends on the backend: for #SVN_FS_TYPE_FSFS, the struct will be
- * of type #svn_fs_fsfs_info_t; otherwise, the struct is guaranteed to be
+ * of type #svn_fs_fsfs_info_t; for #SVN_FS_TYPE_FSX, it will be of type
+ * #svn_fs_fsx_info_t; otherwise, the struct is guaranteed to be
* (compatible with) #svn_fs_info_placeholder_t.
*
- * @see #svn_fs_fsfs_info_t
+ * @see #svn_fs_fsfs_info_t, #svn_fs_fsx_info_t
*
* @since New in 1.9.
*/
@@ -3107,10 +3124,11 @@ svn_fs_info(const svn_fs_info_placeholde
apr_pool_t *scratch_pool);
/**
- * Return a duplicate of @a info, allocated in @a pool. The returned struct
- * will be of the same type as the passed-in struct, which itself must have
- * been returned from svn_fs_info() or svn_fs_info_dup(). No part of the new
- * structure will be shared with @a info (except static string constants).
+ * Return a duplicate of @a info, allocated in @a result_pool. The returned
+ * struct will be of the same type as the passed-in struct, which itself
+ * must have been returned from svn_fs_info() or svn_fs_info_dup(). No part
+ * of the new structure will be shared with @a info (except static string
+ * constants). Use @a scratch_pool for temporary allocations.
*
* @see #svn_fs_info_placeholder_t, #svn_fs_fsfs_info_t
*
