[svn.haxx.se] · SVN Dev · SVN Users · SVN Org · TSVN Dev · TSVN Users · Subclipse Dev · Subclipse Users · this month's index

[PATCH] API documentation fixes and clean-up

From: Julian Foad <julianfoad_at_btopenworld.com>
Date: 2005-04-03 04:39:36 CEST

For review:

[[[
Various fixes to API documentation, partly as a follow-up to recent renaming
of 'force' parameters.

* subversion/include/svn_client.h
   (svn_client_diff, svn_client_diff_peg, svn_client_propset):
     Correct the name of a referenced parameter.
   (svn_client_export2): Add a missing description.

* subversion/include/svn_fs.h
   Create a Doxygen group for Access Context documentation.
   (svn_fs_begin_txn2, svn_fs_commit_txn): Use "@note" to tidy up ugly notes.

* subversion/include/svn_repos.h
   (svn_repos_fs_get_locks): Fix typos.

* subversion/include/svn_wc.h
   (svn_wc_adm_open_anchor): Fix mis-use of "@a".
   (svn_wc_notify_t): Be strict: say the user "must" not "should"
     allocate the structure in an extensible way. Insert a comma.
   (svn_wc_status_set_repos_locks): Fix typos.
   (svn_wc_prop_set): Correct the name of a referenced parameter.
]]]

- Julian

Various fixes to API documentation, partly as a follow-up to recent renaming
of 'force' parameters.

* subversion/include/svn_client.h
  (svn_client_diff, svn_client_diff_peg, svn_client_propset):
    Correct the name of a referenced parameter.
  (svn_client_export2): Add a missing description.

* subversion/include/svn_fs.h
  Create a Doxygen group for Access Context documentation.
  (svn_fs_begin_txn2, svn_fs_commit_txn): Use "@note" to tidy up ugly notes.

* subversion/include/svn_repos.h
  (svn_repos_fs_get_locks): Fix typos.

* subversion/include/svn_wc.h
  (svn_wc_adm_open_anchor): Fix mis-use of "@a".
  (svn_wc_notify_t): Be strict: say the user "must" not "should"
    allocate the structure in an extensible way. Insert a comma.
  (svn_wc_status_set_repos_locks): Fix typos.
  (svn_wc_prop_set): Correct the name of a referenced parameter.

Index: subversion/include/svn_fs.h
===================================================================
--- subversion/include/svn_fs.h (revision 13866)
+++ subversion/include/svn_fs.h (working copy)
@@ -275,11 +275,11 @@
 /** @} */
 
 
-/** Filesystem Access Contexts. (@since New in 1.2.)
- *
- */
-
-/** At certain times, filesystem functions need access to temporary
+/** Filesystem Access Contexts.
+ *
+ * @since New in 1.2.
+ *
+ * At certain times, filesystem functions need access to temporary
  * user data. For example, which user is changing a file? If the
  * file is locked, has an appropriate lock-token been supplied?
  *
@@ -287,7 +287,10 @@
  * and the access context is then connected to the filesystem object.
  * Whenever a filesystem function requires information, it can pull
  * things out of the context as needed.
-*/
+ *
+ * @defgroup svn_fs_access_ctx filesystem access contexts
+ * @{
+ */
 
 /** An opaque object representing temporary user data. */
 typedef struct svn_fs_access_t svn_fs_access_t;
@@ -336,6 +339,7 @@
 svn_error_t *svn_fs_access_add_lock_token (svn_fs_access_t *access_ctx,
                                            const char *token);
 
+/** @} */
 
 
 /** Filesystem Nodes.
@@ -516,10 +520,10 @@
  * @a flags determines transaction enforcement behaviors. See the
  * comments above SVN_FS_TXN_* constants above.
  *
- *<pre> >> Note: if you're building a txn for committing, you probably <<
- * >> don't want to call this directly. Instead, call <<
- * >> @c svn_repos_fs_begin_txn_for_commit(), which honors the <<
- * >> repository's hook configurations. <<</pre>
+ * @note If you're building a txn for committing, you probably
+ * don't want to call this directly. Instead, call
+ * @c svn_repos_fs_begin_txn_for_commit(), which honors the
+ * repository's hook configurations.
  */
 svn_error_t *svn_fs_begin_txn2 (svn_fs_txn_t **txn_p,
                                 svn_fs_t *fs,
@@ -542,9 +546,9 @@
 
 /** Commit @a txn.
  *
- *<pre> >> Note: you usually don't want to call this directly. <<
- * >> Instead, call @c svn_repos_fs_commit_txn(), which honors the <<
- * >> repository's hook configurations. <<</pre>
+ * @note You usually don't want to call this directly.
+ * Instead, call @c svn_repos_fs_commit_txn(), which honors the
+ * repository's hook configurations.
  *
  * If the transaction conflicts with other changes committed to the
  * repository, return an @c SVN_ERR_FS_CONFLICT error. Otherwise, create
Index: subversion/include/svn_repos.h
===================================================================
--- subversion/include/svn_repos.h (revision 13866)
+++ subversion/include/svn_repos.h (working copy)
@@ -1033,8 +1033,8 @@
 
 
 /** Look up all the locks in and under @a path in @a repos, setting @a
- * locks to a hash which maps @c const char * paths to the @c
- * svn_lock_t locks associate with those paths. Use @a
+ * *locks to a hash which maps <tt>const char *</tt> paths to the @c
+ * svn_lock_t locks associated with those paths. Use @a
  * authz_read_func and @a authz_read_baton to "screen" all returned
  * locks. That is: do not return any locks on any paths that are
  * unreadable in HEAD, just silently omit them.
Index: subversion/include/svn_wc.h
===================================================================
--- subversion/include/svn_wc.h (revision 13866)
+++ subversion/include/svn_wc.h (working copy)
@@ -207,7 +207,7 @@
  *
  * @a depth determines the depth used when opening @a path if @a path is a
  * versioned directory, @a depth is ignored otherwise. If @a write_lock is
- * @a TRUE the access batons will hold write locks.
+ * true the access batons will hold write locks.
  *
  * If @a cancel_func is non-null, call it with @a cancel_baton to determine
  * if the client has cancelled the operation.
@@ -599,7 +599,7 @@
  * (i.e., not relative to an anchor). @c action describes what happened
  * to @c path.
  *
- * @c kind, @c content_state @c prop_state and @c lock_state are from
+ * @c kind, @c content_state, @c prop_state and @c lock_state are from
  * after @c action, not before. @c lock_state reflects the addition
  * or removal of a lock token in the working copy.
  *
@@ -634,7 +634,7 @@
  * (i.e., whether or not to attempt deduction, or just to punt and
  * give a less informative notification).
  *
- * @note Callers of notification functions should use @c svn_wc_create_notify
+ * @note Callers of notification functions must use @c svn_wc_create_notify
  * to create structures of this type to allow for extensibility. */
 typedef struct svn_wc_notify_t {
   const char *path;
@@ -1681,7 +1681,7 @@
 /** @since New in 1.2.
  *
  * Associate @a locks, a hash table mapping <tt>const char*</tt>
- * absolute repository paths to <tt>svn_lock_t</tt> objects with an
+ * absolute repository paths to <tt>svn_lock_t</tt> objects, with a
  * @a set_locks_baton returned by an earlier call to
  * @c svn_wc_get_status_editor2. @a repos_root is the repository root URL.
  * Perform all allocations in @a pool.
@@ -2362,7 +2362,7 @@
 /**
  * @deprecated Provided for backward compatibility with the 1.1 API.
  *
- * Like svn_wc_prop_set2(), but with @a force always false.
+ * Like svn_wc_prop_set2(), but with @a skip_checks always false.
  */
 svn_error_t *svn_wc_prop_set (const char *name,
                               const svn_string_t *value,
Index: subversion/include/svn_client.h
===================================================================
--- subversion/include/svn_client.h (revision 13866)
+++ subversion/include/svn_client.h (working copy)
@@ -1025,8 +1025,8 @@
 /**
  * @deprecated Provided for backward compatibility with the 1.0 API.
  *
- * Similar to svn_client_diff2(), but with the @a force parameter always set
- * to @c FALSE.
+ * Similar to svn_client_diff2(), but with the @a ignore_content_type
+ * parameter always set to @c FALSE.
  */
 svn_error_t *svn_client_diff (const apr_array_header_t *diff_options,
                               const char *path1,
@@ -1069,8 +1069,8 @@
  * @since New in 1.1.
  * @deprecated Provided for backward compatibility with the 1.1 API.
  *
- * Similar to svn_client_diff_peg2(), but with the @a force parameter always
- * set to @c FALSE.
+ * Similar to svn_client_diff_peg2(), but with the @a ignore_content_type
+ * parameter always set to @c FALSE.
  */
 svn_error_t *svn_client_diff_peg (const apr_array_header_t *diff_options,
                                   const char *path,
@@ -1394,7 +1394,7 @@
 /**
  * @deprecated Provided for backward compatibility with the 1.1 API.
  *
- * Like svn_client_propset2(), but with @a force always false and a
+ * Like svn_client_propset2(), but with @a skip_checks always false and a
  * newly created @a ctx.
  */
 svn_error_t *
@@ -1650,8 +1650,8 @@
  *
  * Similar to svn_client_export3, but with the @a peg_revision
  * parameter always set to @c svn_opt_revision_unspecified, @a
- * ignore_externals always set to FALSE, and @a recurse always set to
- * TRUE.
+ * overwrite set to the value of @a force, @a ignore_externals
+ * always false, and @a recurse always true.
  */
 svn_error_t *
 svn_client_export2 (svn_revnum_t *result_rev,

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sun Apr 3 04:40:56 2005

This is an archived mail posted to the Subversion Dev mailing list.