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

[Alexandre Janniaux]

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