2008-08-29 17:09:30 Stefan Küng napisał(a):
> 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.
> [[[
> 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_auth_get_simple_provider() is also deprecated.
The comment should suggest to use svn_auth_get_simple_provider2().
> */
> 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_auth_get_ssl_client_cert_pw_file_provider() is also deprecated.
svn_auth_get_ssl_client_cert_pw_file_provider2() should be used.
> */
> 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. */
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/.
--
Arfrever Frehtes Taifersar Arahesis
Received on 2008-08-29 17:41:22 CEST