Re: svn commit: r1815293 - in /subversion/trunk/subversion/include: private/svn_wc_private.h svn_client.h

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

Re: svn commit: r1815293 - in /subversion/trunk/subversion/include: private/svn_wc_private.h svn_client.h

Daniel Shahaf-2
Good mornning Julian,

[hidden email] wrote on Wed, 15 Nov 2017 08:10 +0000:
> @@ -6811,6 +6815,7 @@ svn_client_shelves_list(apr_hash_t **she
>   *
>   * @since New in 1.11.
>   */
> +SVN_EXPERIMENTAL

The doxygen docs should indicate that the function is experimental.
(I only found this reading Bert's patch from today.)

The @since is wrong.  I'm not sure whether it should be corrected or
removed (a case could be made that experimental functions shouldn't
have @since tags until they're declared stable).

>  svn_error_t *
>  svn_client_shelves_any(svn_boolean_t *any_shelved,
>                         const char *local_abspath,
> @@ -6824,6 +6829,7 @@ svn_client_shelves_any(svn_boolean_t *an
>   * @a overwrite_existing: If a file at @a patch_abspath exists, overwrite it.
>   * @a paths, @a depth, @a changelists: The selection of local paths to diff.
>   */
> +SVN_EXPERIMENTAL
>  svn_error_t *
>  svn_client_shelf_write_patch(const char *name,
>                               const char *message,
> @@ -6841,6 +6847,7 @@ svn_client_shelf_write_patch(const char
>   * @a reverse: Apply the patch in reverse.
>   * @a dry_run: Don't really apply the changes, just notify what would be done.

Missing @since.

Also, this doesn't render correctly in doxygen: it's rendered as
a single paragraph.  Either blank lines should be added to make each
"@a foo: lorem ipsum" line a paragraph, or @param should be used (we
already use it in a few places).

>   */
> +SVN_EXPERIMENTAL
>  svn_error_t *
>  svn_client_shelf_apply_patch(const char *name,

Cheers,

Daniel
(The incantation to build doxygen locally is "make doc-api"... which doens't
seem to work in out-of-tree builds; I had to run «doxygen - < doc/doxygen.conf»
in the source tree.)
Reply | Threaded
Open this post in threaded view
|

Re: svn commit: r1815293 - in /subversion/trunk/subversion/include: private/svn_wc_private.h svn_client.h

Julian Foad-5
Daniel Shahaf wrote:
>> @@ -6811,6 +6815,7 @@ svn_client_shelves_list(apr_hash_t **she
>>    *
>>    * @since New in 1.11.
>>    */
>> +SVN_EXPERIMENTAL
>
> The doxygen docs should indicate that the function is experimental.
> (I only found this reading Bert's patch from today.)

Thanks for finding these issues.

I added "@warning EXPERIMENTAL" in each Doxygen string.

> The @since is wrong.  I'm not sure whether it should be corrected or
> removed (a case could be made that experimental functions shouldn't
> have @since tags until they're declared stable).

I changed them to 1.10.

>>   svn_error_t *
>>   svn_client_shelves_any(svn_boolean_t *any_shelved,
>>                          const char *local_abspath,
>> @@ -6824,6 +6829,7 @@ svn_client_shelves_any(svn_boolean_t *an
>>    * @a overwrite_existing: If a file at @a patch_abspath exists, overwrite it.
>>    * @a paths, @a depth, @a changelists: The selection of local paths to diff.
>>    */
>> +SVN_EXPERIMENTAL
>>   svn_error_t *
>>   svn_client_shelf_write_patch(const char *name,
>>                                const char *message,
>> @@ -6841,6 +6847,7 @@ svn_client_shelf_write_patch(const char
>>    * @a reverse: Apply the patch in reverse.
>>    * @a dry_run: Don't really apply the changes, just notify what would be done.
>
> Missing @since.

I added it here and in two more functions.

> Also, this doesn't render correctly in doxygen: it's rendered as
> a single paragraph.  Either blank lines should be added to make each
> "@a foo: lorem ipsum" line a paragraph, or @param should be used (we
> already use it in a few places).

I added blank lines, as at least one of the paragraphs declares multiple
parameters which I don't know how to do with @param.

Committed r1816440.

Thanks.
- Julian