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

[PATCH] Replace Note: comments by @note doxygen tags

From: Marcel Gosselin <marcel.gosselin_at_polymtl.ca>
Date: 2005-06-02 14:51:11 CEST

[[[
Replaced "Note:" comments by @note doxygen tags and "Important note:"
by "@par Important:"

* subversion\include\svn_diff.h
* subversion\include\svn_fs.h
* subversion\include\svn_sorts.h
* subversion\include\svn_repos.h
* subversion\include\svn_delta.h
* subversion\include\svn_path.h
* subversion\include\svn_props.h
* subversion\include\svn_io.h
* subversion\include\svn_client.h
* subversion\include\svn_ra.h
* subversion\include\svn_opt.h:
Replaced Note: comments by @note doxygen tags

* subversion\include\svn_wc.h:
Replaced "Note:" comments by @note doxygen tags and "Important note:"
by "@par Important:"
]]]

Marcel Gosselin

Index: subversion/include/svn_diff.h
===================================================================
--- subversion/include/svn_diff.h (revision 14931)
+++ subversion/include/svn_diff.h (working copy)
@@ -21,7 +21,7 @@
  * This is an internalized library for performing contextual diffs
  * between sources of data.
  *
- * NOTE: this is different than Subversion's binary-diffing engine.
+ * @note This is different than Subversion's binary-diffing engine.
  * That API lives in @c svn_delta.h -- see the "text deltas" section. A
  * "text delta" is way of representing precise binary diffs between
  * strings of data. The Subversion client and server send text deltas
@@ -193,7 +193,7 @@
  * Differences, similarities, and conflicts are described by lining up
  * "ranges" of data.
  *
- * Note: these callbacks describe data ranges in units of "tokens".
+ * @note These callbacks describe data ranges in units of "tokens".
  * A "token" is whatever you've defined it to be in your datasource
  * @c svn_diff_fns_t vtable.
  */
Index: subversion/include/svn_fs.h
===================================================================
--- subversion/include/svn_fs.h (revision 14931)
+++ subversion/include/svn_fs.h (working copy)
@@ -159,7 +159,7 @@
  * Two threads may access the same filesystem simultaneously only if
  * they open separate filesystem objects.
  *
- * NOTE: you probably don't want to use this directly. Take a look at
+ * @note You probably don't want to use this directly. Take a look at
  * svn_repos_open() instead.
  *
  * @since New in 1.1.
@@ -169,7 +169,7 @@
 
 /**
  * Return the path to @a fs's repository, allocated in @a pool.
- * Note: this is just what was passed to svn_fs_create() or
+ * @note This is just what was passed to svn_fs_create() or
  * svn_fs_open() -- might be absolute, might not.
  *
  * @since New in 1.1.
@@ -414,7 +414,7 @@
 
 
 /**
- * NOTE: This function is not guaranteed to work with all filesystem
+ * @note This function is not guaranteed to work with all filesystem
  * types. There is currently no un-deprecated equivalent; contact the
  * Subversion developers if you have a need for it.
  *
@@ -592,7 +592,7 @@
  * operations to resolve the conflict, or call svn_fs_abort_txn() to
  * abort the transaction.
  *
- * NOTE: Success or failure of the commit of @a txn is determined by
+ * @note Success or failure of the commit of @a txn is determined by
  * examining the value of @a *new_rev upon this function's return. If
  * the value is a valid revision number, the commit was successful,
  * even though a non-@c NULL function return value may indicate that
@@ -608,7 +608,7 @@
  * discarded, and the filesystem is left unchanged. Use @a pool for
  * any necessary allocations.
  *
- * NOTE: This function first sets the state of @a txn to "dead", and
+ * @note This function first sets the state of @a txn to "dead", and
  * then attempts to purge it and any related data from the filesystem.
  * If some part of the cleanup process fails, @a txn and some portion
  * of its data may remain in the database after this function returns.
@@ -876,7 +876,7 @@
  * FALSE, also return @c NULL if stepping backwards in history to @a
  * prev_history_t would cross a filesystem copy operation.
  *
- * NOTE: If this is the first call to svn_fs_history_prev() for the @a
+ * @note If this is the first call to svn_fs_history_prev() for the @a
  * history object, it could return a history object whose location is
  * the same as the original. This will happen if the original
  * location was an interesting one (where the node was modified, or
@@ -885,12 +885,12 @@
  * returned by svn_fs_node_history(), and instead go ahead and begin
  * calling svn_fs_history_prev().
  *
- * NOTE: This function uses node-id ancestry alone to determine
+ * @note This function uses node-id ancestry alone to determine
  * modifiedness, and therefore does NOT claim that in any of the
  * returned revisions file contents changed, properties changed,
  * directory entries lists changed, etc.
  *
- * ALSO NOTE: The revisions returned for @a path will be older than or
+ * @note The revisions returned for @a path will be older than or
  * the same age as the revision of that path in @a root. That is, if
  * @a root is a revision root based on revision X, and @a path was
  * modified in some revision(s) younger than X, those revisions
@@ -1188,7 +1188,7 @@
  * mutable nodes --- it's just more code.) Further, @a to_root and @a
  * from_root must represent the same filesystem.
  *
- * Note: to do a copy without preserving copy history, use
+ * @note To do a copy without preserving copy history, use
  * svn_fs_revision_link().
  *
  * Do any necessary temporary allocation in @a pool.
@@ -1400,7 +1400,7 @@
 /** Deltify predecessors of paths modified in @a revision in
  * filesystem @a fs. Use @a pool for all allocations.
  *
- * NOTE: This can be a time-consuming process, depending the breadth
+ * @note This can be a time-consuming process, depending the breadth
  * of the changes made in @a revision, and the depth of the history of
  * those changed paths.
  */
@@ -1561,7 +1561,7 @@
  * path (or if @a path doesn't exist in HEAD), return @c
  * SVN_ERR_FS_OUT_OF_DATE.
  *
- * Note: at this time, only files can be locked.
+ * @note At this time, only files can be locked.
  */
 svn_error_t *svn_fs_lock (svn_lock_t **lock,
                           svn_fs_t *fs,
Index: subversion/include/svn_sorts.h
===================================================================
--- subversion/include/svn_sorts.h (revision 14931)
+++ subversion/include/svn_sorts.h (working copy)
@@ -35,7 +35,7 @@
 
 
 /** This structure is used to hold a key/value from a hash table.
- * NOTE: Private. For use by Subversion's own code only. See issue #1644.
+ * @note Private. For use by Subversion's own code only. See issue #1644.
  */
 typedef struct svn_sort__item_t {
   /** pointer to the key */
@@ -113,9 +113,9 @@
  * integer greater than, equal to, or less than 0, according as the first item
  * is greater than, equal to, or less than the second.
  *
- * NOTE: Private. For use by Subversion's own code only. See issue #1644.
+ * @note Private. For use by Subversion's own code only. See issue #1644.
  *
- * NOTE: This function and the @c svn_sort__item_t should go over to APR.
+ * @note This function and the @c svn_sort__item_t should go over to APR.
  */
 apr_array_header_t *
 svn_sort__hash (apr_hash_t *ht,
Index: subversion/include/svn_repos.h
===================================================================
--- subversion/include/svn_repos.h (revision 14931)
+++ subversion/include/svn_repos.h (working copy)
@@ -64,7 +64,7 @@
  * 'authz_write_func', which although sharing this type, would be a
  * different implementation.
  *
- * Note: If someday we want more sophisticated authorization states
+ * @note If someday we want more sophisticated authorization states
  * than just yes/no, @a allowed can become an enum type.
  */
 typedef svn_error_t *(*svn_repos_authz_func_t) (svn_boolean_t *allowed,
@@ -546,7 +546,7 @@
  * merely serve as indications that properties or textual contents
  * were changed.
  *
- * NOTE: this editor driver passes SVN_INVALID_REVNUM for all
+ * @note This editor driver passes SVN_INVALID_REVNUM for all
  * revision parameters in the editor interface except the copyfrom
  * parameter of the add_file() and add_directory() editor functions.
  *
Index: subversion/include/svn_delta.h
===================================================================
--- subversion/include/svn_delta.h (revision 14931)
+++ subversion/include/svn_delta.h (working copy)
@@ -298,7 +298,7 @@
  * since there's nothing else in the delta application's context to
  * supply a path for error messages.)
  *
- * Note: To avoid lifetime issues, @a error_info is copied into
+ * @note To avoid lifetime issues, @a error_info is copied into
  * @a pool or a subpool thereof.
  */
 void svn_txdelta_apply (svn_stream_t *source,
Index: subversion/include/svn_path.h
===================================================================
--- subversion/include/svn_path.h (revision 14931)
+++ subversion/include/svn_path.h (working copy)
@@ -102,7 +102,7 @@
  *
  * The returned basename will be allocated in @a pool.
  *
- * Note: if an empty string is passed, then an empty string will be returned.
+ * @note If an empty string is passed, then an empty string will be returned.
  */
 char *svn_path_basename (const char *path, apr_pool_t *pool);
 
@@ -262,7 +262,7 @@
  * If there are no items in @a targets, set @a *pcommon and (if
  * applicable) @a *pcondensed_targets to @c NULL.
  *
- * NOTE: There is no guarantee that @a *pcommon is within a working
+ * @note There is no guarantee that @a *pcommon is within a working
  * copy. */
 svn_error_t *
 svn_path_condense_targets (const char **pcommon,
@@ -423,7 +423,7 @@
  * doesn't have any special meaning in @a uri at their positions. If no
  * characters need escaping, just return @a uri.
  *
- * NOTE: Currently, this function escapes <, >, ", space, {, }, |, \, ^, and `.
+ * @note Currently, this function escapes <, >, ", space, {, }, |, \, ^, and `.
  * This may be extended in the future to do context-dependent escaping.
  *
  * @since New in 1.1.
Index: subversion/include/svn_props.h
===================================================================
--- subversion/include/svn_props.h (revision 14931)
+++ subversion/include/svn_props.h (working copy)
@@ -153,7 +153,7 @@
  * and dirs, and are visible (and tweakable) by svn client programs
  * and users. Adding these properties causes specific effects.
  *
- * NOTE: the values of these properties are always UTF8-encoded with
+ * @note the values of these properties are always UTF8-encoded with
  * LF line-endings. It is the burden of svn library users to enforce
  * this. Use svn_prop_needs_translation() to discover if a
  * certain property needs translation, and you can use
Index: subversion/include/svn_io.h
===================================================================
--- subversion/include/svn_io.h (revision 14931)
+++ subversion/include/svn_io.h (working copy)
@@ -325,7 +325,7 @@
 /** Set @a *apr_time to the time of last modification of the contents of the
  * file @a path. @a path is utf8-encoded.
  *
- * Note: this is the APR mtime which corresponds to the traditional mtime
+ * @note This is the APR mtime which corresponds to the traditional mtime
  * on Unix, and the last write time on Windows.
  */
 svn_error_t *svn_io_file_affected_time (apr_time_t *apr_time,
@@ -335,7 +335,7 @@
 /** Set the timestamp of file @a path to @a apr_time. @a path is
  * utf8-encoded.
  *
- * Note: this is the APR mtime which corresponds to the traditional mtime
+ * @note This is the APR mtime which corresponds to the traditional mtime
  * on Unix, and the last write time on Windows.
  */
 svn_error_t *svn_io_set_file_affected_time (apr_time_t apr_time,
@@ -628,7 +628,7 @@
  * path. Set @a *dirents to a hash mapping dirent names (<tt>char *</tt>) to
  * enumerated dirent filetypes (@c svn_node_kind_t *).
  *
- * Note: the `.' and `..' directories normally returned by
+ * @note The `.' and `..' directories normally returned by
  * apr_dir_read() are NOT returned in the hash.
  */
 svn_error_t *svn_io_get_dirents (apr_hash_t **dirents,
@@ -903,7 +903,7 @@
 
 
 /** Wrapper for apr_dir_remove(), which see. @a dirname is utf8-encoded.
- * Note: this function has this name to avoid confusion with
+ * @note This function has this name to avoid confusion with
  * svn_io_remove_dir(), which is recursive.
  */
 svn_error_t *
Index: subversion/include/svn_wc.h
===================================================================
--- subversion/include/svn_wc.h (revision 14931)
+++ subversion/include/svn_wc.h (working copy)
@@ -1200,7 +1200,8 @@
  * scheduled for re-addition) are not returned in the hash, unless
  * @a show_hidden is true.
  *
- * Important note: the @a entries hash is the entries cache in @a adm_access
+ * @par Important:
+ * The @a entries hash is the entries cache in @a adm_access
  * and so usually the hash itself, the keys and the values should be treated
  * as read-only. If any of these are modified then it is the caller's
  * responsibility to ensure that the entries file on disk is updated. Treat
@@ -1210,7 +1211,8 @@
  * access to the original schedule. Use a duplicate entry to modify the
  * schedule.
  *
- * Important note: only the entry structures representing files and
+ * @par Important:
+ * Only the entry structures representing files and
  * @c SVN_WC_ENTRY_THIS_DIR contain complete information. The entry
  * structures representing subdirs have only the `kind' and `state'
  * fields filled in. If you want info on a subdir, you must use this
@@ -1289,7 +1291,7 @@
  * When a new directory is entered, @c SVN_WC_ENTRY_THIS_DIR will always
  * be returned first.
  *
- * Note: callers should be aware that each directory will be
+ * @note Callers should be aware that each directory will be
  * returned *twice*: first as an entry within its parent, and
  * subsequently as the '.' entry within itself. The two calls can be
  * distinguished by looking for @c SVN_WC_ENTRY_THIS_DIR in the 'name'
@@ -1382,7 +1384,7 @@
  * svn_wc_get_status_editor() for depths 1 and 2, since the latter
  * two involve multiple return values.
  *
- * NOTE: The status structures may contain a @c NULL ->entry field.
+ * @note The status structures may contain a @c NULL ->entry field.
  * This indicates an item that is not versioned in the working copy.
  */
 
@@ -2147,7 +2149,7 @@
  *
  * If @a path is not found, return the error @c SVN_ERR_ENTRY_NOT_FOUND.
  *
- * NOTE: Due to the way in which "WC-root-ness" is calculated, passing
+ * @note Due to the way in which "WC-root-ness" is calculated, passing
  * a @a path of `.' to this function will always return @c TRUE.
  */
 svn_error_t *svn_wc_is_wc_root (svn_boolean_t *wc_root,
@@ -2933,7 +2935,7 @@
  * copy (and set @a *tempfile to null if appropriate), and return the
  * error @c SVN_ERR_WC_CORRUPT_TEXT_BASE.
  *
- * Note: this is intended for use with both infix and postfix
+ * @note This is intended for use with both infix and postfix
  * text-delta styled editor drivers.
  */
 svn_error_t *svn_wc_transmit_text_deltas (const char *path,
Index: subversion/include/svn_client.h
===================================================================
--- subversion/include/svn_client.h (revision 14931)
+++ subversion/include/svn_client.h (working copy)
@@ -360,7 +360,7 @@
  *
  * All allocations should be performed in @a pool.
  *
- * NOTE: If there is no blame information for this line, @a revision will be
+ * @note If there is no blame information for this line, @a revision will be
  * invalid and @a author and @a date will be NULL.
  */
 typedef svn_error_t *
@@ -2084,7 +2084,7 @@
  * svn_client_uuid_from_url() to retrieve, using the entry's URL. @a
  * ctx is required for possible repository authentication.
  *
- * NOTE: the only reason this function falls back on
+ * @note The only reason this function falls back on
  * svn_client_uuid_from_url() is for compatibility purposes. Old
  * working copies may not have uuids in the entries file.
  */
Index: subversion/include/svn_ra.h
===================================================================
--- subversion/include/svn_ra.h (revision 14931)
+++ subversion/include/svn_ra.h (working copy)
@@ -718,9 +718,9 @@
  * Ask the RA layer to 'diff' a working copy against @a versus_url;
  * it's another form of svn_ra_do_update().
  *
- * [Please note: this function cannot be used to diff a single
- * file, only a working copy directory. See the svn_ra_do_switch()
- * function for more details.]
+ * @note This function cannot be used to diff a single file, only a
+ * working copy directory. See the svn_ra_do_switch() function
+ * for more details.
  *
  * The client initially provides a @a diff_editor/@a baton to the RA
  * layer; this editor contains knowledge of where the common diff
@@ -859,7 +859,7 @@
 /**
  * Set @a *uuid to the repository's UUID.
  *
- * NOTE: the UUID has the same lifetime as the @a session.
+ * @note The UUID has the same lifetime as the @a session.
  *
  * Use @a pool for temporary memory allocation.
  *
@@ -874,7 +874,7 @@
  * a trailing '/'. The returned URL is guaranteed to be a prefix of the
  * @a session's URL.
  *
- * NOTE: the URL has the same lifetime as the @a session.
+ * @note The URL has the same lifetime as the @a session.
  *
  * Use @a pool for temporary memory allocation.
  *
@@ -895,7 +895,7 @@
  *
  * Use @a pool for all allocations.
  *
- * NOTE: This functionality is not available in pre-1.1 servers. If the
+ * @note This functionality is not available in pre-1.1 servers. If the
  * server doesn't implement it, an @c SVN_ERR_RA_NOT_IMPLEMENTED error is
  * returned.
  *
@@ -927,7 +927,7 @@
  * empty file. In the following calls, the delta will be against the
  * fulltext contents for the previous call.
  *
- * NOTE: This functionality is not available in pre-1.1 servers. If the
+ * @note This functionality is not available in pre-1.1 servers. If the
  * server doesn't implement it, an @c SVN_ERR_RA_NOT_IMPLEMENTED error is
  * returned.
  *
Index: subversion/include/svn_opt.h
===================================================================
--- subversion/include/svn_opt.h (revision 14931)
+++ subversion/include/svn_opt.h (working copy)
@@ -169,7 +169,7 @@
 /**
  * Various ways of specifying revisions.
  *
- * Note:
+ * @note
  * In contexts where local mods are relevant, the `working' kind
  * refers to the uncommitted "working" revision, which may be modified
  * with respect to its base revision. In other contexts, `working'
@@ -229,9 +229,7 @@
  * If @a arg is invalid, return -1; else return 0.
  * It is invalid to omit a revision (as in, ":", "N:" or ":M").
  *
- * Note:
- *
- * It is typical, though not required, for @a *start_revision and
+ * @note It is typical, though not required, for @a *start_revision and
  * @a *end_revision to be @c svn_opt_revision_unspecified kind on entry.
  *
  * Use @a pool for temporary allocations.

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Thu Jun 2 15:10:30 2005

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