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

Re: Deprecated functions should say what replaces them [was: An unexpected effect of new 'deprecated' tags.]

From: Stefan Küng <tortoisesvn_at_gmail.com>
Date: Fri, 29 Aug 2008 16:14:09 +0200

Julian Foad wrote:
> Stefan Küng wrote:
>> One thing that bugged me about the deprecated functions for some time
>> now is the doxygen comment. All deprecated functions only have a text
>> like "\deprecated: provided for backward compatibility with the 1.x
>> API". But it doesn't say which function to use instead.
>>
>> For most functions, that's not a big problem: only look for a function
>> with the same name but a higher number at the end (e.g.,
>> svn_client_merge3 instead of svn_client_merge2). But there are some
>> functions which don't have that:
>>
>> svn_client_ls3 is deprecated, but there is no svn_client_ls4
>> svn_client_get_* (auth provider functions) also have no 'higher number
>> function'.
>>
>> For svn_client_ls3, the function to use would be svn_client_list2, and
>> for the auth provider functions it would be the svn_auth_get_* functions.
>>
>> A user who doesn't follow the commits has to search the whole docs to
>> find the new function to use.
>>
>> So I suggest to extend those doxygen comments like this:
>> "\deprecated: provided for backward compatibility with the 1.x API. Use
>> svn_client_list() instead."
>>
>> This would make it immediately clear which function superseeds the
>> deprecated one.
>
> +1. Can you send a patch? I think this is only necessary for the
> functions where it is not just a higher number.

Patch attached.
If it's ok, I'll commit it.

Stefan

-- 
       ___
  oo  // \\      "De Chelonian Mobile"
 (_,\/ \_/ \     TortoiseSVN
   \ \_/_\_/>    The coolest Interface to (Sub)Version Control
   /_/   \_\     http://tortoisesvn.net

[[[
Document which function replaces deprecated functions.
* subversion/include/svn_client.h,
  subversion/include/svn_cmdline.h: add doc string.
]]]
Index: subversion/include/svn_client.h
===================================================================
--- subversion/include/svn_client.h (revision 32806)
+++ subversion/include/svn_client.h (working copy)
@@ -104,6 +104,7 @@
  * re-prompt @a retry_limit times (via svn_auth_next_credentials()).
  *
  * @deprecated Provided for backward compatibility with the 1.3 API.
+ * Use @a svn_auth_get_simple_prompt_provider instead.
  */
 SVN_DEPRECATED
 void
@@ -127,6 +128,7 @@
  * re-prompt @a retry_limit times (via svn_auth_next_credentials()).
  *
  * @deprecated Provided for backward compatibility with the 1.3 API.
+ * Use @a svn_auth_get_username_prompt_provider instead.
  */
 SVN_DEPRECATED
 void
@@ -150,6 +152,7 @@
  * SVN_AUTH_PARAM_DEFAULT_PASSWORD).
  *
  * @deprecated Provided for backward compatibility with the 1.3 API.
+ * Use @a svn_auth_get_simple_provider instead.
  */
 SVN_DEPRECATED
 void
@@ -178,6 +181,7 @@
  * if the password were not cached at all.
  *
  * @deprecated Provided for backward compatibility with the 1.3 API.
+ * Use @a svn_auth_get_windows_simple_provider instead.
  */
 SVN_DEPRECATED
 void
@@ -195,6 +199,7 @@
  * @c SVN_AUTH_PARAM_DEFAULT_USERNAME).
  *
  * @deprecated Provided for backward compatibility with the 1.3 API.
+ * Use @a svn_auth_get_username_provider instead.
  */
 SVN_DEPRECATED
 void
@@ -210,6 +215,7 @@
  * security on an error.
  *
  * @deprecated Provided for backward compatibility with the 1.3 API.
+ * Use @a svn_auth_get_ssl_server_trust_file_provider instead.
  */
 SVN_DEPRECATED
 void
@@ -226,6 +232,7 @@
  * client certificate for authentication when requested by a server.
  *
  * @deprecated Provided for backward compatibility with the 1.3 API.
+ * Use @a svn_auth_get_ssl_client_cert_file_provider instead.
  */
 SVN_DEPRECATED
 void
@@ -242,6 +249,7 @@
  * certificate is protected by a passphrase.
  *
  * @deprecated Provided for backward compatibility with the 1.3 API.
+ * Use @a svn_auth_get_ssl_client_cert_pw_file_provider instead.
  */
 SVN_DEPRECATED
 void
@@ -258,6 +266,7 @@
  * SSL security on an error.
  *
  * @deprecated Provided for backward compatibility with the 1.3 API.
+ * Use @a svn_auth_get_ssl_server_trust_prompt_provider instead.
  */
 SVN_DEPRECATED
 void
@@ -277,6 +286,7 @@
  * a server. The prompt will be retried @a retry_limit times.
  *
  * @deprecated Provided for backward compatibility with the 1.3 API.
+ * Use @a svn_auth_get_ssl_client_cert_prompt_provider instead.
  */
 SVN_DEPRECATED
 void
@@ -297,6 +307,7 @@
  * be retried @a retry_limit times.
  *
  * @deprecated Provided for backward compatibility with the 1.3 API.
+ * Use @a svn_auth_get_ssl_client_cert_pw_prompt_provider instead.
  */
 SVN_DEPRECATED
 void
@@ -801,20 +812,24 @@
 
   /** notification callback function.
    * This will be called by notify_func2() by default.
- * @deprecated Provided for backward compatibility with the 1.1 API. */
+ * @deprecated Provided for backward compatibility with the 1.1 API.
+ * Use @a svn_wc_notify_func2_t instead. */
   svn_wc_notify_func_t notify_func;
 
   /** notification callback baton for notify_func()
- * @deprecated Provided for backward compatibility with the 1.1 API. */
+ * @deprecated Provided for backward compatibility with the 1.1 API.
+ * Use @a notify_baton2 instead */
   void *notify_baton;
 
   /** Log message callback function. NULL means that Subversion
     * should try not attempt to fetch a log message.
- * @deprecated Provided for backward compatibility with the 1.2 API. */
+ * @deprecated Provided for backward compatibility with the 1.2 API.
+ * Use @a svn_client_get_commit_log2_t instead. */
   svn_client_get_commit_log_t log_msg_func;
 
   /** log message callback baton
- * @deprecated Provided for backward compatibility with the 1.2 API. */
+ * @deprecated Provided for backward compatibility with the 1.2 API.
+ * Use @a log_msg_baton2 instead. */
   void *log_msg_baton;
 
   /** a hash mapping of <tt>const char *</tt> configuration file names to
@@ -2947,6 +2962,7 @@
  * resolution support.
  *
  * @deprecated Provided for backward compatibility with the 1.4 API.
+ * Use @a svn_client_resolve instead.
  */
 SVN_DEPRECATED
 svn_error_t *
@@ -3937,6 +3953,7 @@
  * @since New in 1.3.
  *
  * @deprecated Provided for backward compatibility with the 1.3 API.
+ * Use @a svn_client_list2 instead.
  */
 SVN_DEPRECATED
 svn_error_t *
@@ -3955,6 +3972,7 @@
  * @since New in 1.2.
  *
  * @deprecated Provided for backward compatibility with the 1.2 API.
+ * Use @a svn_client_list2 instead.
  */
 SVN_DEPRECATED
 svn_error_t *
@@ -3971,6 +3989,7 @@
  * the same as @a revision.
  *
  * @deprecated Provided for backward compatibility with the 1.1 API.
+ * Use @a svn_client_list2 instead.
  */
 SVN_DEPRECATED
 svn_error_t *
Index: subversion/include/svn_cmdline.h
===================================================================
--- subversion/include/svn_cmdline.h (revision 32806)
+++ subversion/include/svn_cmdline.h (working copy)
@@ -325,6 +325,7 @@
  *
  * @since New in 1.4.
  * @deprecated Provided for backward compatibility with the 1.5 API.
+ * Use @a svn_cmdline_set_up_auth_baton instead.
  *
  * @note This deprecation does not follow the usual pattern of putting
  * a new number on end of the function's name. Instead, the new

Received on 2008-08-29 16:14:30 CEST

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

This site is subject to the Apache Privacy Policy and the Apache Public Forum Archive Policy.