[PATCH weston 04/11] make the backends compositor-neutral

[Giulio Camuffo]

2015-06-24 4:05 GMT+03:00 Jon A. Cruz <jonc at osg.samsung.com>:
> Just a few minor low-level items in this feedback...
>
[snip]
>> diff --git a/src/compositor.c b/src/compositor.c
>> index 6e111f1..b063265 100644
>> --- a/src/compositor.c
>> +++ b/src/compositor.c
>> @@ -4544,6 +4544,43 @@ fail:
>>       return NULL;
>>  }
>>
>
> In general it's more expected to see the doxygen comment in the .h where
> this is declared, not the .c where it is defined.

In Wayland and Weston all the documentation is in the .c files, so
better keep it consistent.

>
> "\brief" not needed. Just end with a period (as is the case here) and
> auto-brief of doxygen covers it.
>
>> +/** \brief Init the backend for the given compositor.
>> + *
>> + * This function loads the passed \c backend with the given
>> + * config on the given compositor. Returns 0 on success, -1
>> + * on failure.
>> + * \c backend can either be a full path to the backend plugin
>> + * or a relative one, in which case the path is resolved
>> + * based on libweston's install prefix.
>> + * The backend configuration object must be a pointer to an
>> + * object whose type is a backend specific subclass of
>> + * \ref weston_backend_config.
>
> Generally "\ref" is not needed. Doxygen will recognize globals and
> structs when prefixed with '::' and functions when followed by '()'.
> Following the "less is more" doxygen approach also helps with
> integrating documentation from different areas.
>
> So here, "subclass of ::weston_backend_config" most likely will suffice.
>
[snip]