Hi All,
I am a new-comer to the Subversion code-base. I was looking at some of the
header files (svn_path.h) and wanted to use some of the functions
(svn_path_join()) and noticed that they were deprecated. I thought it
would be nice to have a link to the deprecating functions as a part of
the documentation. Hence this patch.
The log message and patch are as follows.
[[[
Improved the documentation of deprecated functions by providing links
to the deprecating functions.
* subversion/include/svn_path.h
(svn_path_internal_style, svn_path_local_style,
svn_path_join, svn_path_join_many,
svn_path_basename, svn_path_dirname,
svn_path_split, svn_path_canonicalize,
svn_path_is_canonical, svn_path_get_longest_ancestor,
svn_path_get_absolute, svn_path_split,
svn_path_condense_targets, svn_path_is_child,
svn_path_is_ancestor, svn_path_split_if_file,
svn_path_url_add_component)
Patch by: Arwin Arni <arwin_at_collab.net>
]]]
Index: subversion/include/svn_path.h
===================================================================
--- subversion/include/svn_path.h (revision 1032465)
+++ subversion/include/svn_path.h (working copy)
@@ -64,6 +64,10 @@
/** Convert @a path from the local style to the canonical internal style.
+ *
+ * New code should use either svn_dirent_internal_style() (for local
paths) or
+ * svn_relpath_internal_style() (for relative paths).
+ *
* @deprecated Provided for backward compatibility with the 1.6 API.
*/
SVN_DEPRECATED
@@ -71,6 +75,10 @@
svn_path_internal_style(const char *path, apr_pool_t *pool);
/** Convert @a path from the canonical internal style to the local style.
+ *
+ * New code should use either svn_dirent_local_style() (for local paths) or
+ * svn_relpath_local_style() (for relative paths).
+ *
* @deprecated Provided for backward compatibility with the 1.6 API.
*/
SVN_DEPRECATED
@@ -101,6 +109,9 @@
* @a component won't be detected. An absolute URI can only be used
* for the base.
*
+ * New code should use either svn_dirent_join() (for local paths) or
+ * svn_uri_join() (for urls) or svn_relpath_join() (for relative paths).
+ *
* @deprecated Provided for backward compatibility with the 1.6 API.
*/
SVN_DEPRECATED
@@ -118,7 +129,9 @@
* This function does not support URLs.
*
* See svn_path_join() for further notes about joining paths.
- *
+ *
+ * New code should use svn_dirent_join_many() instead.
+ *
* @deprecated Provided for backward compatibility with the 1.6 API.
*/
SVN_DEPRECATED
@@ -139,7 +152,7 @@
* @note If an empty string is passed, then an empty string will be
returned.
*
* New code should use either svn_dirent_basename() (for local paths) or
- * svn_uri_basename() (for urls and repository paths).
+ * svn_uri_basename() (for urls) or svn_relpath_basename (for relative
paths).
*
* @deprecated Provided for backward compatibility with the 1.6 API.
*/
@@ -154,7 +167,7 @@
* The returned dirname will be allocated in @a pool.
*
* New code should use either svn_dirent_dirname() (for local paths) or
- * svn_uri_dirname() (for urls and repository paths).
+ * svn_uri_dirname() (for urls) or svn_relpath_dirname() (for relative
paths).
*
* @deprecated Provided for backward compatibility with the 1.6 API.
*/
@@ -227,7 +240,7 @@
* - <pre>"" ==> "" and ""</pre>
*
* New code should use either svn_dirent_split() (for local paths) or
- * svn_uri_split() (for urls and repository paths).
+ * svn_uri_split() (for urls) or svn_relpath_split() (for relative paths).
*
* @deprecated Provided for backward compatibility with the 1.6 API.
*/
@@ -266,6 +279,10 @@
* The returned path may be statically allocated, equal to @a path, or
* allocated from @a pool.
*
+ * New code should use either svn_dirent_canonicalize() (for local
paths) or
+ * svn_uri_canonicalize() (for urls) or svn_relpath_canonicalize() (for
+ * relative paths).
+ *
* @deprecated Provided for backward compatibility with the 1.6 API.
*/
SVN_DEPRECATED
@@ -275,6 +292,10 @@
/** Return @c TRUE iff path is canonical. Use @a pool for temporary
* allocations.
*
+ * New code should use either svn_dirent_is_canonical() (for local
paths) or
+ * svn_uri_is_canonical() (for urls) or svn_relpath_is_canonical() (for
+ * relative paths).
+ *
* @since New in 1.5.
* @deprecated Provided for backward compatibility with the 1.6 API.
*/
@@ -300,6 +321,10 @@
* different resources), and (b) share a common ancestor in their path
* component, i.e. 'protocol://' is not a sufficient ancestor.
*
+ * New code should use either svn_dirent_get_longest_ancestor()
+ * (for local paths) or svn_uri_get_longest_ancestor() (for urls)
+ * or svn_relpath_get_longest_ancestor() (for relative paths).
+ *
* @deprecated Provided for backward compatibility with the 1.6 API.
*/
SVN_DEPRECATED
@@ -314,6 +339,8 @@
* @a relative may be a URL, in which case no attempt is made to
convert it,
* and a copy of the URL is returned.
*
+ * New code should use svn_dirent_get_absolute() instead.
+ *
* @deprecated Provided for backward compatibility with the 1.6 API.
*/
SVN_DEPRECATED
@@ -328,6 +355,9 @@
* empty string. If @a path does not exist it is treated as if it is
* a file, since directories do not normally vanish.
*
+ * New code should use either svn_dirent_split() (for local paths) or
+ * svn_uri_split() (for urls) or svn_relpath_split() (for relative paths).
+ *
* @deprecated Provided for backward compatibility with the 1.6 API.
*/
SVN_DEPRECATED
@@ -365,6 +395,9 @@
* If there are no items in @a targets, set @a *pcommon and (if
* applicable) @a *pcondensed_targets to @c NULL.
*
+ * New code should use either svn_dirent_condense_targets() (for local
paths) or
+ * svn_uri_condense_targets() (for urls).
+ *
* @note There is no guarantee that @a *pcommon is within a working
* copy.
*
@@ -489,6 +522,10 @@
* in which case a pointer into @a path2 will be returned to
* identify the remainder path.
*
+ * New code should use either svn_dirent_is_child() (for local paths) or
+ * svn_uri_is_child() (for urls) or svn_relpath_is_child()
+ * (for relative paths).
+ *
* @deprecated Provided for backward compatibility with the 1.6 API.
*/
SVN_DEPRECATED
@@ -499,6 +536,11 @@
* and FALSE otherwise.
*
* @since New in 1.3.
+ *
+ * New code should use either svn_dirent_is_ancestor() (for local paths) or
+ * svn_uri_is_ancestor() (for urls) or svn_relpath_is_ancestor() (for
relative
+ * paths).
+ *
* @deprecated Provided for backward compatibility with the 1.6 API.
*/
SVN_DEPRECATED
@@ -584,7 +626,7 @@
const char *component,
apr_pool_t *pool);
-/** Like svn_path_url_add_component2, but allows path components that
+/** Like svn_path_url_add_component2(), but allows path components that
* end with a trailing '/'
*
* @deprecated Provided for backward compatibility with the 1.5 API.
