Julian Foad wrote:
> On Fri, 2008-08-29 at 16:14 +0200, Stefan Küng wrote:
>> Julian Foad wrote:
>>> Stefan Küng wrote:
>>>> 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.
>
> In Doxygen mark-up, to refer to another function, just give the
> function's name with "()" after it like in your example above, and to
> refer to another non-function such as a type, use the "@c" prefix. (I
> think of "@c" as "Cross-reference".) We use "@a" to refer to an Argument
> of the present function.
>
> To refer to a function-type, I would use "@c". From within the
> documentation of a member of a structure, to refer to another member of
> the same structure, I would use "@c". (I don't know that these are
> consistently used conventions.)
>
> Other than that, I expect your patch is fine. I haven't gone through and
> checked that you've specified the right successor in each case, but I
> would trust that you've got it right or very nearly so. You've got my +1
> to commit it after the above tweak. You might want to wait a few hours
> in case abybody else reviews it, but then again you might not and you
> don't have to! (It can still be reviewed after check-in.)
Thanks for the review!
I've changed the patch according to your advice. New patch is attached.
I've also checked the doxygen output to make sure the function names are
properly turned into links to the corresponding doc part.
I'll wait a few hours in case someone else wants to review this.
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_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 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_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 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 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 @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. */
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
Received on 2008-08-29 17:09:54 CEST