From 5af6a1a0128b5776a1d66a55e7296c58aff72e97 Mon Sep 17 00:00:00 2001 From: Laurent Pinchart Date: Sat, 12 Oct 2019 01:23:14 +0300 Subject: libcamera: control_ids: Fix documentation for controls namespace MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Jacopo Mondi Tested-by: Niklas Söderlund Reviewed-by: Niklas Söderlund --- 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 f699ac9e..dd543382 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 0899e40b..a3e52fb3 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): -- cgit v1.2.1