[libcamera-devel] [PATCH v2 02/14] libcamera: control_ids: Fix documentation for controls namespace

[Niklas Söderlund]

Hi Laurent,

Thanks for your patch.

On 2019-10-12 21:43:55 +0300, Laurent Pinchart wrote:
> The controls namespace isn't documenting, making it impossible to
> reference the variables it contains. Furthermore, within the
> documentation page for the control_ids.h file, links from overview to
> detailed variable documentation are broken for the same reason. Both
> issues can be fixed by documenting the controls namespace.
> 
> Unfortunately doxygen then fails to parse the initialisers for the
> controls global variables correctly and considers them as functions. To
> work around this, modify the control_ids.cpp generation script to hide
> the variables from doxygen, but still expose their documentation.
> 
> Signed-off-by: Laurent Pinchart <laurent.pinchart at ideasonboard.com>

Reviewed-by: Niklas Söderlund <niklas.soderlund at ragnatech.se>

> ---
>  src/libcamera/control_ids.cpp.in | 13 ++++++++++++-
>  src/libcamera/gen-controls.py    | 18 ++++++++++++------
>  2 files changed, 24 insertions(+), 7 deletions(-)
> 
> diff --git a/src/libcamera/control_ids.cpp.in b/src/libcamera/control_ids.cpp.in
> index f699ac9eea54..dd5433820a8b 100644
> --- a/src/libcamera/control_ids.cpp.in
> +++ b/src/libcamera/control_ids.cpp.in
> @@ -16,9 +16,20 @@
>  
>  namespace libcamera {
>  
> +/**
> + * \brief Namespace for libcamera controls
> + */
>  namespace controls {
>  
> -${controls}
> +${controls_doc}
> +
> +#ifndef __DOXYGEN__
> +/*
> + * Keep the controls definitions hidden from doxygen as it incorrectly parses
> + * them as functions.
> + */
> +${controls_def}
> +#endif
>  
>  } /* namespace controls */
>  
> diff --git a/src/libcamera/gen-controls.py b/src/libcamera/gen-controls.py
> index 0899e40b4080..a3e52fb36f7a 100755
> --- a/src/libcamera/gen-controls.py
> +++ b/src/libcamera/gen-controls.py
> @@ -17,12 +17,14 @@ def snake_case(s):
>  
>  
>  def generate_cpp(controls):
> -    template = string.Template('''/**
> +    doc_template = string.Template('''/**
> + * \\var extern const Control<${type}> ${name}
>  ${description}
> - */
> -extern const Control<${type}> ${name}(${id_name}, "${name}");''')
> + */''')
> +    def_template = string.Template('extern const Control<${type}> ${name}(${id_name}, "${name}");')
>  
> -    ctrls = []
> +    ctrls_doc = []
> +    ctrls_def = []
>  
>      for ctrl in controls:
>          name, ctrl = ctrl.popitem()
> @@ -39,9 +41,13 @@ extern const Control<${type}> ${name}(${id_name}, "${name}");''')
>              'id_name': id_name,
>          }
>  
> -        ctrls.append(template.substitute(info))
> +        ctrls_doc.append(doc_template.substitute(info))
> +        ctrls_def.append(def_template.substitute(info))
>  
> -    return {'controls': '\n\n'.join(ctrls)}
> +    return {
> +        'controls_doc': '\n\n'.join(ctrls_doc),
> +        'controls_def': '\n'.join(ctrls_def),
> +    }
>  
>  
>  def generate_h(controls):
> -- 
> Regards,
> 
> Laurent Pinchart
> 
> _______________________________________________
> libcamera-devel mailing list
> libcamera-devel at lists.libcamera.org
> https://lists.libcamera.org/listinfo/libcamera-devel

-- 
Regards,
Niklas Söderlund