[{"id":2879,"web_url":"https://patchwork.libcamera.org/comment/2879/","msgid":"<20191013152036.GK23166@bigcity.dyn.berto.se>","date":"2019-10-13T15:20:36","subject":"Re: [libcamera-devel] [PATCH v2 02/14] libcamera: control_ids: Fix\n\tdocumentation for controls namespace","submitter":{"id":5,"url":"https://patchwork.libcamera.org/api/people/5/","name":"Niklas Söderlund","email":"niklas.soderlund@ragnatech.se"},"content":"Hi Laurent,\n\nThanks for your patch.\n\nOn 2019-10-12 21:43:55 +0300, Laurent Pinchart wrote:\n> The controls namespace isn't documenting, making it impossible to\n> reference the variables it contains. Furthermore, within the\n> documentation page for the control_ids.h file, links from overview to\n> detailed variable documentation are broken for the same reason. Both\n> issues can be fixed by documenting the controls namespace.\n> \n> Unfortunately doxygen then fails to parse the initialisers for the\n> controls global variables correctly and considers them as functions. To\n> work around this, modify the control_ids.cpp generation script to hide\n> the variables from doxygen, but still expose their documentation.\n> \n> Signed-off-by: Laurent Pinchart \n\nReviewed-by: Niklas Söderlund \n\n> ---\n> src/libcamera/control_ids.cpp.in | 13 ++++++++++++-\n> src/libcamera/gen-controls.py | 18 ++++++++++++------\n> 2 files changed, 24 insertions(+), 7 deletions(-)\n> \n> diff --git a/src/libcamera/control_ids.cpp.in b/src/libcamera/control_ids.cpp.in\n> index f699ac9eea54..dd5433820a8b 100644\n> --- a/src/libcamera/control_ids.cpp.in\n> +++ b/src/libcamera/control_ids.cpp.in\n> @@ -16,9 +16,20 @@\n> \n> namespace libcamera {\n> \n> +/**\n> + * \\brief Namespace for libcamera controls\n> + */\n> namespace controls {\n> \n> -${controls}\n> +${controls_doc}\n> +\n> +#ifndef __DOXYGEN__\n> +/*\n> + * Keep the controls definitions hidden from doxygen as it incorrectly parses\n> + * them as functions.\n> + */\n> +${controls_def}\n> +#endif\n> \n> } /* namespace controls */\n> \n> diff --git a/src/libcamera/gen-controls.py b/src/libcamera/gen-controls.py\n> index 0899e40b4080..a3e52fb36f7a 100755\n> --- a/src/libcamera/gen-controls.py\n> +++ b/src/libcamera/gen-controls.py\n> @@ -17,12 +17,14 @@ def snake_case(s):\n> \n> \n> def generate_cpp(controls):\n> - template = string.Template('''/**\n> + doc_template = string.Template('''/**\n> + * \\\\var extern const Control<${type}> ${name}\n> ${description}\n> - */\n> -extern const Control<${type}> ${name}(${id_name}, \"${name}\");''')\n> + */''')\n> + def_template = string.Template('extern const Control<${type}> ${name}(${id_name}, \"${name}\");')\n> \n> - ctrls = []\n> + ctrls_doc = []\n> + ctrls_def = []\n> \n> for ctrl in controls:\n> name, ctrl = ctrl.popitem()\n> @@ -39,9 +41,13 @@ extern const Control<${type}> ${name}(${id_name}, \"${name}\");''')\n> 'id_name': id_name,\n> }\n> \n> - ctrls.append(template.substitute(info))\n> + ctrls_doc.append(doc_template.substitute(info))\n> + ctrls_def.append(def_template.substitute(info))\n> \n> - return {'controls': '\\n\\n'.join(ctrls)}\n> + return {\n> + 'controls_doc': '\\n\\n'.join(ctrls_doc),\n> + 'controls_def': '\\n'.join(ctrls_def),\n> + }\n> \n> \n> def generate_h(controls):\n> -- \n> Regards,\n> \n> Laurent Pinchart\n> \n> _______________________________________________\n> libcamera-devel mailing list\n> libcamera-devel@lists.libcamera.org\n> https://lists.libcamera.org/listinfo/libcamera-devel","headers":{"Return-Path":"","Received":["from mail-lj1-x241.google.com (mail-lj1-x241.google.com\n\t[IPv6:2a00:1450:4864:20::241])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 732A961562\n\tfor ;\n\tSun, 13 Oct 2019 17:20:37 +0200 (CEST)","by mail-lj1-x241.google.com with SMTP id m7so14188723lji.2\n\tfor ;\n\tSun, 13 Oct 2019 08:20:37 -0700 (PDT)","from localhost (h-93-159.A463.priv.bahnhof.se. [46.59.93.159])\n\tby smtp.gmail.com with ESMTPSA id\n\th9sm3420091lfp.40.2019.10.13.08.20.36\n\t(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n\tSun, 13 Oct 2019 08:20:36 -0700 (PDT)"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=ragnatech-se.20150623.gappssmtp.com; s=20150623;\n\th=date:from:to:cc:subject:message-id:references:mime-version\n\t:content-disposition:content-transfer-encoding:in-reply-to\n\t:user-agent; bh=scri+21lM6PZFuuJN8hAac4udCq1Z6umW9OpQwNol9I=;\n\tb=fVlN3npjSJtq/aFm1vGcFJF1hJb1cmAr8BGJP6+VSXl7LIChJQIXevscfIW3AxA5Er\n\tSE+xKh1KUAqIz07WFk7loHkRO1UwoWLj58YbZDPr9A/SJXqGE8WYHY/+jknwchLMbfjY\n\thqQAHPFNKPYrlvBabHI5J9xiRSC/5Er2nhkzE2tJzprGYzd1i/37P4TUzrHqLkw46Ek2\n\trupnItzU43JgE9onlscvgVJvajIpzLDj4gijOJzGUrmADUKk2+HIKUByDaBgmCzAXe+k\n\tt2YTKGEy7b/pETvkNdyVi8ihkHMlEi3pgiknNGof3iJIG2D0hRGLQrnu+Lq0JQOsh5zV\n\t+dMA==","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20161025;\n\th=x-gm-message-state:date:from:to:cc:subject:message-id:references\n\t:mime-version:content-disposition:content-transfer-encoding\n\t:in-reply-to:user-agent;\n\tbh=scri+21lM6PZFuuJN8hAac4udCq1Z6umW9OpQwNol9I=;\n\tb=hB8ckvfTnCDQIO4e0GdXCnuzBCpNK75+2uJj/Bq4UFdkSsS/ysyG49cmuhVapkgTAq\n\tnDEiDd+3rS6hC5frCbcWRreabsGzVdz1zv/N7UL0rxocgzoME/6QlPqOEo+k8nZ+owSt\n\tkpkoGXnGoEU1rmEDgyPZ93XH3Jwt5ARs38HOZLE8IfMeOJxADF9CQ3JwUhEDOfTJNkyH\n\ta2/HZL9h/GnZoQu7oYVXqW1lmDHCu2KTTmpldpdNisVix4i7EG9bT3T712X6IX8Mr8gn\n\t/fkvS7uKf5p2G2NSp6nMAGz4xWDUYsfothDJu+URKgnj9YbOq4QKBrpwHcrObC+9MX8K\n\tws8A==","X-Gm-Message-State":"APjAAAUQYsp4iCjBzcySu5q6JXTUpNR2Kry8TKo9YaMFw9R6g/nB6M0P\n\tCnHD+MfqjeHP0ZouZgJBsfhJWIFzE8o=","X-Google-Smtp-Source":"APXvYqynMP86KxGmFLQP15bc7D8ikCJERQBN2R98UKvKHyIdB1+xw/n0l523kdOriPTTDQ17Mpa7IQ==","X-Received":"by 2002:a2e:9112:: with SMTP id m18mr2840464ljg.75.1570980036886;\n\tSun, 13 Oct 2019 08:20:36 -0700 (PDT)","Date":"Sun, 13 Oct 2019 17:20:36 +0200","From":"Niklas =?iso-8859-1?q?S=F6derlund?= ","To":"Laurent Pinchart ","Cc":"libcamera-devel@lists.libcamera.org","Message-ID":"<20191013152036.GK23166@bigcity.dyn.berto.se>","References":"<20191012184407.31684-1-laurent.pinchart@ideasonboard.com>\n\t<20191012184407.31684-3-laurent.pinchart@ideasonboard.com>","MIME-Version":"1.0","Content-Type":"text/plain; charset=iso-8859-1","Content-Disposition":"inline","Content-Transfer-Encoding":"8bit","In-Reply-To":"<20191012184407.31684-3-laurent.pinchart@ideasonboard.com>","User-Agent":"Mutt/1.12.1 (2019-06-15)","Subject":"Re: [libcamera-devel] [PATCH v2 02/14] libcamera: control_ids: Fix\n\tdocumentation for controls namespace","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.29","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","X-List-Received-Date":"Sun, 13 Oct 2019 15:20:37 -0000"}}]