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