Hi Hans, On Tuesday, 19 September 2017 14:04:36 EEST Hans Verkuil wrote: > On 09/19/17 12:48, Laurent Pinchart wrote: > > 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.ailus@xxxxxxxxxxxxxxx> > >> Reviewed-by: Niklas Söderlund <niklas.soderlund+renesas@xxxxxxxxxxxx> > >> Acked-by: Hans Verkuil <hans.verkuil@xxxxxxxxx> > >> Acked-by: Pavel Machek <pavel@xxxxxx> > > > > 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. When writing a driver you can use the compiled documentation. We're lacking reviewers in V4L2, we should make their life easier if we want to attract more. Furthermore, if documentation becomes stale, it will become useless for driver authors, regardless of where it's stored. > >> --- > >> > >> drivers/media/v4l2-core/v4l2-fwnode.c | 75 ----------------------------- > >> include/media/v4l2-fwnode.h | 81 +++++++++++++++++++++++++++- > >> 2 files changed, 80 insertions(+), 76 deletions(-) -- Regards, Laurent Pinchart -- To unsubscribe from this list: send the line "unsubscribe devicetree" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
