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.
- Julian
> [[[
> 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
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe_at_subversion.tigris.org
For additional commands, e-mail: dev-help_at_subversion.tigris.org
Received on 2008-08-29 16:46:36 CEST