Re: [PATCH] To improve the documentation of svn_path.h

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