[vlc-devel] [PATCH 1/4] playlist: fix detailed description

[Rémi Denis-Courmont]

I haven't tested, but it seems odd to put comments between an ingroup stanza and its start marker.

Le 5 avril 2019 10:09:48 GMT+03:00, Alexandre Janniaux <ajanni at videolabs.io> a écrit :
>Hi, thank you for the review.
>
>Could you be more specific? AFAIR in the doxygen documentation, special
>comment block preceding member group contains documentation for the 
>member
>group, like preceding comment block before a function contains 
>documentation
>for the function. I might misunderstand it but it seems to produce the 
>correct
>result, even when detailed description is already defined somewhere 
>else, and
>matches the examples on the doxygen documentation.
>
>from doxygen documentation [1]:
>> Before the opening marker of a block a separate comment block may be 
>> placed.
>> This block should contain the @name (or \name) command and is used to
>
>> specify
>> the header of the group. Optionally, the comment block may also
>contain 
>> more
>> detailed information about the group.
>
>The fact that detailed information was inside the member group led to 
>having
>input_item_t inherit the group documentation [2].
>
>Do I misinterpret your review? There are maybe other issues \like file 
>documentation
>but I don't really know this part.
>
>[1]: http://www.doxygen.nl/manual/grouping.html#memgroup
>[2]: 
>https://www.videolan.org/developers/vlc/doc/doxygen/html/group__playlist.html#ga1656e9a2f1c25f8b7a0085c7af33f9c8
>
>On 2019-04-05 06:52, Rémi Denis-Courmont wrote:
>> AFAIU how Doxygen works, this is incorrect.
>> 
>> Le 4 avril 2019 23:51:14 GMT+03:00, Alexandre Janniaux
>> <ajanni at videolabs.io> a écrit :
>>> ---
>>> include/vlc_playlist.h | 7 +++----
>>> 1 file changed, 3 insertions(+), 4 deletions(-)
>>> 
>>> diff --git a/include/vlc_playlist.h b/include/vlc_playlist.h
>>> index 52edae9957..47561134fe 100644
>>> --- a/include/vlc_playlist.h
>>> +++ b/include/vlc_playlist.h
>>> @@ -30,10 +30,7 @@ extern "C" {
>>> /**
>>>  * \defgroup playlist playlist
>>>  * \ingroup playlist
>>> - * @{
>>> - */
>>> -
>>> -/**
>>> + *
>>>  * A VLC playlist contains a list of "playlist items".
>>>  *
>>> * Each playlist item contains exactly one media (input item). In the
>>> future,
>>> @@ -102,6 +99,8 @@ extern "C" {
>>> * may have changed the list. Therefore, vlc_playlist_Request*()
>>> functions are
>>> * exposed to resolve potential conflicts and apply the changes. The
>>> actual
>>>  * changes applied are notified through the callbacks
>>> + *
>>> + * @{
>>>  */
>>> 
>>> /* forward declarations */
>>> --
>>> 2.21.0
>>> 
>>> _______________________________________________
>>> vlc-devel mailing list
>>> To unsubscribe or modify your subscription options:
>>> https://mailman.videolan.org/listinfo/vlc-devel
>> 
>> _______________________________________________
>> vlc-devel mailing list
>> To unsubscribe or modify your subscription options:
>> https://mailman.videolan.org/listinfo/vlc-devel
>_______________________________________________
>vlc-devel mailing list
>To unsubscribe or modify your subscription options:
>https://mailman.videolan.org/listinfo/vlc-devel

-- 
Envoyé de mon appareil Android avec Courriel K-9 Mail. Veuillez excuser ma brièveté.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.videolan.org/pipermail/vlc-devel/attachments/20190405/0031400b/attachment.html>