On 09/19/17 12:48, Laurent Pinchart wrote:
> Hi Sakari,
>
> Thank you for the patch.
>
> On Friday, 15 September 2017 17:17:00 EEST Sakari Ailus wrote:
>> In V4L2 the practice is to have the KernelDoc documentation in the header
>> and not in .c source code files. This consequently makes the V4L2 fwnode
>> function documentation part of the Media documentation build.
>>
>> Also correct the link related function and argument naming in
>> documentation.
>>
>> Signed-off-by: Sakari Ailus <sakari.ai...@linux.intel.com>
>> Reviewed-by: Niklas Söderlund <niklas.soderlund+rene...@ragnatech.se>
>> Acked-by: Hans Verkuil <hans.verk...@cisco.com>
>> Acked-by: Pavel Machek <pa...@ucw.cz>
>
> I'm still very opposed to this. In addition to increasing the risk of
> documentation becoming stale, it also makes review more difficult. I'm
> reviewing patch 05/25 of this series and I have to jump around the patch to
> verify that the documentation matches the implementation, it's really
> annoying.
>
> We should instead move all function documentation from header files to source
> files.
I disagree with this. Yes, it makes reviewing harder, but when you have to
*use* these functions as e.g. a driver developer, then having it in the
header is much more convenient.
Regards,
Hans
>
>> ---
>> drivers/media/v4l2-core/v4l2-fwnode.c | 75 --------------------------------
>> include/media/v4l2-fwnode.h | 81 +++++++++++++++++++++++++++++++-
>> 2 files changed, 80 insertions(+), 76 deletions(-)
>
> [snip]
>
