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

[Kieran Bingham]

Hi Laurent, Jacopo,

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?

> 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?

> 
> 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
--
Kieran