You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Arwin Arni <ar...@collab.net> on 2010/11/08 15:27:44 UTC
[PATCH] To improve the documentation of svn_path.h
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.
Re: [PATCH] To improve the documentation of svn_path.h
Posted by Kamesh Jayachandran <ka...@collab.net>.
>> [[[
>> 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,
Thanks Arwin for the patch 'svn_path_split_if_file' is deprectated but
svn_{uri|dirent|relpath}_split do not seem like its deprecating
function. So removed that portion from your patch.
Committed the patch at r1032610.
With regards
Kamesh Jayachandran
>> svn_path_url_add_component)
>>
Re: [PATCH] To improve the documentation of svn_path.h
Posted by Arwin Arni <ar...@collab.net>.
On Monday 08 November 2010 07:57 PM, Arwin Arni wrote:
> 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.
Sorry folks. I forgot to attach the patch file.
Regards,
Arwin Arni
Re: [PATCH] To improve the documentation of svn_path.h
Posted by Arwin Arni <ar...@collab.net>.
On Monday 08 November 2010 07:57 PM, Arwin Arni wrote:
> 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.
Sorry folks. I forgot to attach the patch file.
Regards,
Arwin Arni