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

[PATCH] To improve the documentation of svn_path.h

From: Arwin Arni <arwin_at_collab.net>
Date: Mon, 08 Nov 2010 19:57:44 +0530

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.
Received on 2010-11-08 15:28:30 CET

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