From patchwork Sat Oct 12 18:43:55 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Laurent Pinchart X-Patchwork-Id: 2163 Return-Path: Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 1192B6196E for ; Sat, 12 Oct 2019 20:44:16 +0200 (CEST) Received: from pendragon.bb.dnainternet.fi (dfj612yhrgyx302h3jwwy-3.rev.dnainternet.fi [IPv6:2001:14ba:21f5:5b00:ce28:277f:58d7:3ca4]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 6D9BA33A for ; Sat, 12 Oct 2019 20:44:15 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1570905855; bh=SsVqKXaIVcdlWRXP2hsy95tJFefEHTZPpJr/BetEt8w=; h=From:To:Subject:Date:In-Reply-To:References:From; b=bFTGZU01ICwYWQFqcMoVsGuQbVKUwHfDC+NcD01OSIp7G7DFvKDtk2V/9AjoBYlDy nxK830fxvvQnaU6GK3XKNB041DC7vfAJnOp5qTAh4IaY7J1GwCSfgerlUgRvY3zDdW u0myajHAG6gd02K6GbDwkt3wSoypNZLJ/MYaJ+kY= From: Laurent Pinchart To: libcamera-devel@lists.libcamera.org Date: Sat, 12 Oct 2019 21:43:55 +0300 Message-Id: <20191012184407.31684-3-laurent.pinchart@ideasonboard.com> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20191012184407.31684-1-laurent.pinchart@ideasonboard.com> References: <20191012184407.31684-1-laurent.pinchart@ideasonboard.com> MIME-Version: 1.0 Subject: [libcamera-devel] [PATCH v2 02/14] libcamera: control_ids: Fix documentation for controls namespace X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sat, 12 Oct 2019 18:44:16 -0000 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: 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 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):