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

[Alexandre Janniaux]

 From what I understand, if you put \ingroup above a class,
file or namespace, it will take precedence over the
\defgroup, \addtogroup or \weakgroup. However, if you put it
in a comment block defining a module group it applies to the
module group itself and that's the feature allowing module
group nesting.

After that, AFAIU how doxygen works, the order of command in
a special comment block doesn't matter. So I can swap the
\ingroup and \defgroup commands if you prefer it that way.


On 2019-04-05 09:25, Rémi Denis-Courmont wrote:
> 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
> 
> _______________________________________________
> vlc-devel mailing list
> To unsubscribe or modify your subscription options:
> https://mailman.videolan.org/listinfo/vlc-devel