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

Arfrever Frehtes Taifersar Arahesis wrote:

>> @@ -150,6 +152,7 @@
>> * SVN_AUTH_PARAM_DEFAULT_PASSWORD).
>> *
>> * @deprecated Provided for backward compatibility with the 1.3 API.
>> + * Use svn_auth_get_simple_provider() instead.
>
> svn_auth_get_simple_provider() is also deprecated.
> The comment should suggest to use svn_auth_get_simple_provider2().

>> @@ -242,6 +249,7 @@
>> * certificate is protected by a passphrase.
>> *
>> * @deprecated Provided for backward compatibility with the 1.3 API.
>> + * Use svn_auth_get_ssl_client_cert_pw_file_provider() instead.
>
> svn_auth_get_ssl_client_cert_pw_file_provider() is also deprecated.
> svn_auth_get_ssl_client_cert_pw_file_provider2() should be used.
>

>> @@ -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 @c svn_wc_notify_func2_t instead. */
>
> Maybe s/svn_wc_notify_func2_t/notify_func2/.
>
>> 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 @c 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 @c svn_client_get_commit_log2_t instead. */
>
> Maybe s/svn_client_get_commit_log2_t/log_msg_func2/.
>

Thanks for the review. New patch attached which contains your improvements.

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 32809)
+++ 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 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 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 svn_auth_get_simple_provider2() 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 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 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 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 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 svn_auth_get_ssl_client_cert_pw_file_provider2() instead.
  */
 SVN_DEPRECATED
 void
@@ -258,6 +266,7 @@
  * SSL security on an error.
  *
  * @deprecated Provided for backward compatibility with the 1.3 API.
+ * Use 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 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 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 @c notify_func2 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 @c 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 @c log_msg_func2 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 @c 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 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 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 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 svn_client_list2() instead.
  */
 SVN_DEPRECATED
 svn_error_t *
Index: subversion/include/svn_cmdline.h
===================================================================
--- subversion/include/svn_cmdline.h (revision 32809)
+++ 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 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