Re: [PATCH 19/24] media: vb2-core: Improve kernel-doc markups

[Mauro Carvalho Chehab <mchehab@s-opensource.com>]

Em Tue, 10 Oct 2017 16:32:34 +0300
Sakari Ailus <sakari.ailus@iki.fi> escreveu:

> Hi Mauro,
> 
> On Mon, Oct 09, 2017 at 07:19:25AM -0300, Mauro Carvalho Chehab wrote:
> > There are several issues on the current markups:
> > - lack of cross-references;
> > - wrong cross-references;
> > - lack of a period of the end of several phrases;
> > - Some descriptions can be enhanced.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > ---
> >  include/media/videobuf2-core.h | 376 ++++++++++++++++++++++-------------------
> >  1 file changed, 204 insertions(+), 172 deletions(-)
> > 
> > diff --git a/include/media/videobuf2-core.h b/include/media/videobuf2-core.h
> > index 0308d8439049..e145f1475ffe 100644
> > --- a/include/media/videobuf2-core.h
> > +++ b/include/media/videobuf2-core.h  
> 
> ...
> 
> >  /**
> >   * vb2_core_queue_init() - initialize a videobuf2 queue
> > - * @q:		videobuf2 queue; this structure should be allocated in driver
> > + * @q:		pointer to &struct vb2_queue with videobuf2 queue.
> > + *		This structure should be allocated in driver
> >   *
> >   * The &vb2_queue structure should be allocated by the driver. The driver is
> >   * responsible of clearing it's content and setting initial values for some
> >   * required entries before calling this function.
> > - * q->ops, q->mem_ops, q->type and q->io_modes are mandatory. Please refer
> > - * to the struct vb2_queue description in include/media/videobuf2-core.h
> > - * for more information.
> > + *
> > + * .. note::
> > + *
> > + *    The following fields at @q should be set before calling this function:  
> 
> should -> shall
> 
> I bet there's a lot of that in the documentation elsewhere, including this
> patch.

Yes, there are, and not only on this file (where it uses should
everywhere).

I prefer to do such change globally.

For now, I'll apply this patch as-is.

Thanks,
Mauro