[libcamera-devel] [PATCH 03/31] libcamera: gen-controls: Fix documentation issue with <<

[Laurent Pinchart]

Hi Kieran,

On Mon, Mar 02, 2020 at 10:25:20PM +0000, Kieran Bingham wrote:
> On 29/02/2020 16:42, Laurent Pinchart wrote:
> > From: Jacopo Mondi <jacopo at jmondi.org>
> > 
> > Doxygen fails to parse entries with multiple << signs as, in example,
> > \var extern const Control<Span<int32_t>>
> 
> Is this a bug in Doxygen? Has it been reported?

I believe it is. https://github.com/doxygen/doxygen/issues/7625

> > Remove the type from the control documentation as unique control and
> > properties name should not need any additional information specified for
> > Doxygen to correctly identify them.
> > 
> > Not sure this patch is the right way to fix this, but it's mostly here
> > to highlight an issue.
> 
> If the unique control/property name is enough to satisfy doxygen, then
> I'd remove this last sentence and call this a suitable workaround...
> 
> In fact I'd say more than a workaround, this should be fine. We don't
> normally have to specify the full type declaration for variables?

Yes, I think that's fine. I'll remove the last sentence.

> > Signed-off-by: Jacopo Mondi <jacopo at jmondi.org>
> 
> Reviewed-by: Kieran Bingham <kieran.bingham at ideasonboard.com>
> 
> > ---
> >  src/libcamera/gen-controls.py | 2 +-
> >  1 file changed, 1 insertion(+), 1 deletion(-)
> > 
> > diff --git a/src/libcamera/gen-controls.py b/src/libcamera/gen-controls.py
> > index 773e9b5d170c..6f020a327827 100755
> > --- a/src/libcamera/gen-controls.py
> > +++ b/src/libcamera/gen-controls.py
> > @@ -29,7 +29,7 @@ def generate_cpp(controls):
> >      enum_doc_value_template = string.Template(''' * \\var ${name}Values::${value}
> >  ${description}''')
> >      doc_template = string.Template('''/**
> > - * \\var extern const Control<${type}> ${name}
> > + * \\var ${name}
> >  ${description}
> >   */''')
> >      def_template = string.Template('extern const Control<${type}> ${name}(${id_name}, "${name}");')
> > 

-- 
Regards,

Laurent Pinchart