{"id":20727,"url":"https://patchwork.libcamera.org/api/1.1/patches/20727/?format=json","web_url":"https://patchwork.libcamera.org/patch/20727/","project":{"id":1,"url":"https://patchwork.libcamera.org/api/1.1/projects/1/?format=json","name":"libcamera","link_name":"libcamera","list_id":"libcamera_core","list_email":"libcamera-devel@lists.libcamera.org","web_url":"","scm_url":"","webscm_url":""},"msgid":"<20240731135201.2866145-4-dan.scally@ideasonboard.com>","date":"2024-07-31T13:52:00","name":"[v4,3/4] libcamera: Documentation: Split public/private documentation","commit_ref":null,"pull_url":null,"state":"superseded","archived":false,"hash":"3da9a251529398b917a04ccae300cc1fcc535cd9","submitter":{"id":156,"url":"https://patchwork.libcamera.org/api/1.1/people/156/?format=json","name":"Dan Scally","email":"dan.scally@ideasonboard.com"},"delegate":null,"mbox":"https://patchwork.libcamera.org/patch/20727/mbox/","series":[{"id":4469,"url":"https://patchwork.libcamera.org/api/1.1/series/4469/?format=json","web_url":"https://patchwork.libcamera.org/project/libcamera/list/?series=4469","date":"2024-07-31T13:51:57","name":"Improve libcamera documentation","version":4,"mbox":"https://patchwork.libcamera.org/series/4469/mbox/"}],"comments":"https://patchwork.libcamera.org/api/patches/20727/comments/","check":"pending","checks":"https://patchwork.libcamera.org/api/patches/20727/checks/","tags":{},"headers":{"Return-Path":"","X-Original-To":"parsemail@patchwork.libcamera.org","Delivered-To":"parsemail@patchwork.libcamera.org","Received":["from lancelot.ideasonboard.com (lancelot.ideasonboard.com\n\t[92.243.16.209])\n\tby patchwork.libcamera.org (Postfix) with ESMTPS id 1C598C32BB\n\tfor ;\n\tWed, 31 Jul 2024 13:52:27 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 761316337E;\n\tWed, 31 Jul 2024 15:52:23 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[IPv6:2001:4b98:dc2:55:216:3eff:fef7:d647])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id B729D6336F\n\tfor ;\n\tWed, 31 Jul 2024 15:52:17 +0200 (CEST)","from mail.ideasonboard.com\n\t(cpc141996-chfd3-2-0-cust928.12-3.cable.virginm.net [86.13.91.161])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id C3430144C;\n\tWed, 31 Jul 2024 15:51:29 +0200 (CEST)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"EnbwQOBZ\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1722433889;\n\tbh=UeKLZEtkcZZuMn7ikSa88iVd6Zrpvrmebes5w9msJxY=;\n\th=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n\tb=EnbwQOBZ28X8ESqltDoI2op6Z5JISiw7mroOaG9Fkq8DQtO3z6SwSJgbEMcMwXCYl\n\tjFegZlPaZemE08NOrYDvrujDph6jbSzuIjkfuDoqkyA56mbjw8wyoJGheapxNHxjIt\n\t18MyQnEsA9M9x4sKADD7wd8QSw6JSTQwVqwNu5bw=","From":"Daniel Scally ","To":"libcamera-devel@lists.libcamera.org","Cc":"Daniel Scally ,\n\tJacopo Mondi ,\n\tKieran Bingham ","Subject":"[PATCH v4 3/4] libcamera: Documentation: Split public/private\n\tdocumentation","Date":"Wed, 31 Jul 2024 14:52:00 +0100","Message-Id":"<20240731135201.2866145-4-dan.scally@ideasonboard.com>","X-Mailer":"git-send-email 2.34.1","In-Reply-To":"<20240731135201.2866145-1-dan.scally@ideasonboard.com>","References":"<20240731135201.2866145-1-dan.scally@ideasonboard.com>","MIME-Version":"1.0","Content-Transfer-Encoding":"8bit","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","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "},"content":"The API reference pages generated by Doxygen are comprehensive, but\ntherefore quite overwhelming for application developers who will\nlikely never need to use the majority of the library's objects. To\nreduce the complexity of the documentation, split it into two runs of\ndoxygen.\n\nIn the first run of doxygen we pass a specific list of source files\nto parse, which is built from the File arrays in Meson's build files.\nThis ensures that we only generate the documentation for code from\nthose files.\n\nIn the second run allow doxygen to generate documentation for all of\nthe library's objects as it currently does. This set will now be\noutput into build/Documentation/internal-api-html.\n\nReviewed-by: Jacopo Mondi \nReviewed-by: Kieran Bingham \nSigned-off-by: Daniel Scally \n---\nChanges in v4:\n\n\t- Reversed the split methodology to include a common Doxyfile in both of\n\t the internal and public Doxyfiles, rather than generating a separate\n\t include for each. This simplies the meson.build.\n\nChanges in v3:\n\n\t- A typo\n\t- Explicitly excluded include/libcamera/internal/span.h in\n\t Doxyfile-public.in\n\nChanges in v2:\n\n\t- Formatting fixes (Jacopo)\n\t- Phraseology (Laurent)\n\t- Switched to passing specific files to parse to doxygen rather than\n\t relying on \\internal to remove other docu-comments.\n\n Documentation/Doxyfile-internal.in | 30 ++++++++++++++++\n Documentation/Doxyfile-public.in | 15 ++++++++\n Documentation/Doxyfile.in | 23 ------------\n Documentation/meson.build | 48 +++++++++++++++++++++++---\n include/libcamera/base/meson.build | 7 ++++\n include/libcamera/internal/meson.build | 7 ++++\n include/libcamera/meson.build | 10 ++++++\n meson.build | 8 +++++\n src/libcamera/base/class.cpp | 1 +\n src/libcamera/base/meson.build | 7 ++++\n src/libcamera/camera.cpp | 7 ++++\n src/libcamera/camera_manager.cpp | 1 +\n src/libcamera/framebuffer.cpp | 6 +++-\n src/libcamera/meson.build | 7 ++++\n src/libcamera/request.cpp | 1 +\n 15 files changed, 149 insertions(+), 29 deletions(-)\n create mode 100644 Documentation/Doxyfile-internal.in\n create mode 100644 Documentation/Doxyfile-public.in","diff":"diff --git a/Documentation/Doxyfile-internal.in b/Documentation/Doxyfile-internal.in\nnew file mode 100644\nindex 00000000..9d4cf9d9\n--- /dev/null\n+++ b/Documentation/Doxyfile-internal.in\n@@ -0,0 +1,30 @@\n+# SPDX-License-Identifier: CC-BY-SA-4.0\n+\n+@INCLUDE_PATH = @TOP_BUILDDIR@/Documentation\n+@INCLUDE = Doxyfile\n+\n+HIDE_UNDOC_CLASSES = NO\n+HIDE_UNDOC_MEMBERS = NO\n+HTML_OUTPUT = internal-api-html\n+INTERNAL_DOCS = YES\n+\n+INPUT = \"@TOP_SRCDIR@/Documentation\" \\\n+ \"@TOP_SRCDIR@/include/libcamera\" \\\n+ \"@TOP_SRCDIR@/src/ipa/ipu3\" \\\n+ \"@TOP_SRCDIR@/src/ipa/libipa\" \\\n+ \"@TOP_SRCDIR@/src/libcamera\" \\\n+ \"@TOP_BUILDDIR@/include/libcamera\" \\\n+ \"@TOP_BUILDDIR@/src/libcamera\"\n+\n+EXCLUDE = @TOP_SRCDIR@/include/libcamera/base/span.h \\\n+ @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_sysfs.h \\\n+ @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_udev.h \\\n+ @TOP_SRCDIR@/include/libcamera/internal/ipc_pipe_unixsocket.h \\\n+ @TOP_SRCDIR@/src/libcamera/device_enumerator_sysfs.cpp \\\n+ @TOP_SRCDIR@/src/libcamera/device_enumerator_udev.cpp \\\n+ @TOP_SRCDIR@/src/libcamera/ipc_pipe_unixsocket.cpp \\\n+ @TOP_SRCDIR@/src/libcamera/pipeline/ \\\n+ @TOP_SRCDIR@/src/libcamera/tracepoints.cpp \\\n+ @TOP_BUILDDIR@/include/libcamera/internal/tracepoints.h \\\n+ @TOP_BUILDDIR@/include/libcamera/ipa/soft_ipa_interface.h \\\n+ @TOP_BUILDDIR@/src/libcamera/proxy/\ndiff --git a/Documentation/Doxyfile-public.in b/Documentation/Doxyfile-public.in\nnew file mode 100644\nindex 00000000..7fbe53d5\n--- /dev/null\n+++ b/Documentation/Doxyfile-public.in\n@@ -0,0 +1,15 @@\n+# SPDX-License-Identifier: CC-BY-SA-4.0\n+\n+@INCLUDE_PATH = @TOP_BUILDDIR@/Documentation\n+@INCLUDE = Doxyfile\n+\n+HIDE_UNDOC_CLASSES = YES\n+HIDE_UNDOC_MEMBERS = YES\n+HTML_OUTPUT = api-html\n+INTERNAL_DOCS = NO\n+\n+INPUT = \"@TOP_SRCDIR@/Documentation\" \\\n+ \"@INPUT@\" \\\n+ \"@TOP_BUILDDIR@/src/libcamera/version.cpp\"\n+\n+EXCLUDE = @TOP_SRCDIR@/include/libcamera/base/span.h\ndiff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in\nindex dd1d909b..a70aee43 100644\n--- a/Documentation/Doxyfile.in\n+++ b/Documentation/Doxyfile.in\n@@ -22,14 +22,6 @@ CASE_SENSE_NAMES = YES\n QUIET = YES\n WARN_AS_ERROR = @WARN_AS_ERROR@\n \n-INPUT = \"@TOP_SRCDIR@/Documentation\" \\\n- \"@TOP_SRCDIR@/include/libcamera\" \\\n- \"@TOP_SRCDIR@/src/ipa/ipu3\" \\\n- \"@TOP_SRCDIR@/src/ipa/libipa\" \\\n- \"@TOP_SRCDIR@/src/libcamera\" \\\n- \"@TOP_BUILDDIR@/include/libcamera\" \\\n- \"@TOP_BUILDDIR@/src/libcamera\"\n-\n FILE_PATTERNS = *.c \\\n *.cpp \\\n *.dox \\\n@@ -37,19 +29,6 @@ FILE_PATTERNS = *.c \\\n \n RECURSIVE = YES\n \n-EXCLUDE = @TOP_SRCDIR@/include/libcamera/base/span.h \\\n- @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_sysfs.h \\\n- @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_udev.h \\\n- @TOP_SRCDIR@/include/libcamera/internal/ipc_pipe_unixsocket.h \\\n- @TOP_SRCDIR@/src/libcamera/device_enumerator_sysfs.cpp \\\n- @TOP_SRCDIR@/src/libcamera/device_enumerator_udev.cpp \\\n- @TOP_SRCDIR@/src/libcamera/ipc_pipe_unixsocket.cpp \\\n- @TOP_SRCDIR@/src/libcamera/pipeline/ \\\n- @TOP_SRCDIR@/src/libcamera/tracepoints.cpp \\\n- @TOP_BUILDDIR@/include/libcamera/internal/tracepoints.h \\\n- @TOP_BUILDDIR@/include/libcamera/ipa/soft_ipa_interface.h \\\n- @TOP_BUILDDIR@/src/libcamera/proxy/\n-\n EXCLUDE_PATTERNS = @TOP_BUILDDIR@/include/libcamera/ipa/*_serializer.h \\\n @TOP_BUILDDIR@/include/libcamera/ipa/*_proxy.h \\\n @TOP_BUILDDIR@/include/libcamera/ipa/ipu3_*.h \\\n@@ -72,8 +51,6 @@ EXCLUDE_SYMBOLS = libcamera::BoundMethodArgs \\\n \n EXCLUDE_SYMLINKS = YES\n \n-HTML_OUTPUT = api-html\n-\n GENERATE_LATEX = NO\n \n MACRO_EXPANSION = YES\ndiff --git a/Documentation/meson.build b/Documentation/meson.build\nindex 30d39523..8349d924 100644\n--- a/Documentation/meson.build\n+++ b/Documentation/meson.build\n@@ -24,12 +24,22 @@ if doxygen.found() and dot.found()\n \n cdata.set('PREDEFINED', ' \\\\\\n\\t\\t\\t '.join(doxygen_predefined))\n \n+ # We run doxygen twice - the first run excludes internal API objects as it\n+ # is intended to document the public API only. A second run covers all of\n+ # the library's objects for libcamera developers. Common configuration is\n+ # set in an initially generated Doxyfile, which is then included by the two\n+ # final Doxyfiles. We collected a list of the public sources in\n+ # doxygen_public_sources to pass to the public run and include it in cdata\n+ # here - although both Doxyfile and Doxyfile-internal will also receive\n+ # the same parameter they simply ignore it.\n+\n+ cdata.set('INPUT', '\" \\\\\\n\\t\\t\\t \"'.join(doxygen_public_sources))\n+\n doxyfile = configure_file(input : 'Doxyfile.in',\n output : 'Doxyfile',\n configuration : cdata)\n \n- doxygen_input = [\n- doxyfile,\n+ global_doxygen_input = [\n libcamera_base_headers,\n libcamera_base_sources,\n libcamera_internal_headers,\n@@ -42,16 +52,44 @@ if doxygen.found() and dot.found()\n ]\n \n if is_variable('ipu3_ipa_sources')\n- doxygen_input += [ipu3_ipa_sources]\n+ global_doxygen_input += [ipu3_ipa_sources]\n endif\n \n+ # This is the \"public\" run of doxygen generating an abridged version of the\n+ # API's documentation, as informed by the INPUT parameter in cdata.\n+\n+ doxyfile_public = configure_file(input : 'Doxyfile-public.in',\n+ output : 'Doxyfile-public',\n+ configuration : cdata)\n+\n+ public_doxygen_input = global_doxygen_input\n+ public_doxygen_input += doxyfile_public\n+\n custom_target('doxygen',\n- input : doxygen_input,\n+ input : public_doxygen_input,\n output : 'api-html',\n- command : [doxygen, doxyfile],\n+ command : [doxygen, doxyfile_public],\n install : true,\n install_dir : doc_install_dir,\n install_tag : 'doc')\n+\n+ # This is the internal documentation, which hard-codes a list of directories\n+ # to parse in its doxyfile and so ignores the INPUT parameter from cdata.\n+\n+ doxyfile_internal = configure_file(input : 'Doxyfile-internal.in',\n+ output : 'Doxyfile-internal',\n+ configuration : cdata)\n+\n+ internal_doxygen_input = global_doxygen_input\n+ internal_doxygen_input += doxyfile_internal\n+\n+ custom_target('doxygen-internal',\n+ input : internal_doxygen_input,\n+ output : 'internal-api-html',\n+ command : [doxygen, doxyfile_internal],\n+ install : true,\n+ install_dir : doc_install_dir,\n+ install_tag : 'doc-internal')\n endif\n \n #\ndiff --git a/include/libcamera/base/meson.build b/include/libcamera/base/meson.build\nindex bace25d5..837ef40a 100644\n--- a/include/libcamera/base/meson.build\n+++ b/include/libcamera/base/meson.build\n@@ -38,3 +38,10 @@ libcamera_base_headers = [\n \n install_headers(libcamera_base_public_headers,\n subdir : libcamera_base_include_dir)\n+\n+foreach lbph : libcamera_base_public_headers\n+\tdoxygen_public_sources += '/'.join(\n+\t\tmeson.project_source_root(),\n+\t\t'@0@'.format(lbph)\n+\t)\n+endforeach\ndiff --git a/include/libcamera/internal/meson.build b/include/libcamera/internal/meson.build\nindex 76c939bf..53fc2846 100644\n--- a/include/libcamera/internal/meson.build\n+++ b/include/libcamera/internal/meson.build\n@@ -60,5 +60,12 @@ libcamera_internal_headers = [\n libcamera_internal_headers_undocumented,\n ]\n \n+foreach lph : libcamera_internal_headers_documented\n+\tdoxygen_public_sources += '/'.join(\n+\t\tmeson.project_source_root(),\n+\t\t'@0@'.format(lph)\n+\t)\n+endforeach\n+\n subdir('converter')\n subdir('software_isp')\ndiff --git a/include/libcamera/meson.build b/include/libcamera/meson.build\nindex 84c6c4cb..59273785 100644\n--- a/include/libcamera/meson.build\n+++ b/include/libcamera/meson.build\n@@ -26,6 +26,13 @@ subdir('ipa')\n install_headers(libcamera_public_headers,\n subdir : libcamera_include_dir)\n \n+foreach lph : libcamera_public_headers\n+\tdoxygen_public_sources += '/'.join(\n+\t\tmeson.project_source_root(),\n+\t\t'@0@'.format(lph)\n+\t)\n+endforeach\n+\n #\n # Generate headers from templates.\n #\n@@ -86,6 +93,7 @@ foreach mode, entry : controls_map\n '-r', ranges_file, '@INPUT@'],\n install : true,\n install_dir : libcamera_headers_install_dir)\n+ doxygen_public_sources += control_headers.get(-1).full_path()\n endforeach\n \n libcamera_public_headers += control_headers\n@@ -102,6 +110,7 @@ formats_h = custom_target('formats_h',\n install : true,\n install_dir : libcamera_headers_install_dir)\n libcamera_public_headers += formats_h\n+doxygen_public_sources += formats_h.full_path()\n \n # libcamera.h\n libcamera_h = custom_target('gen-header',\n@@ -112,6 +121,7 @@ libcamera_h = custom_target('gen-header',\n install_dir : libcamera_headers_install_dir)\n \n libcamera_public_headers += libcamera_h\n+doxygen_public_sources += libcamera_h.full_path()\n \n # version.h\n version = libcamera_version.split('.')\ndiff --git a/meson.build b/meson.build\nindex 2acd8c3e..8084f2fb 100644\n--- a/meson.build\n+++ b/meson.build\n@@ -241,6 +241,14 @@ endif\n # Utilities are parsed first to provide support for other components.\n subdir('utils')\n \n+# To support auto-generation of documentation we need an array of the paths to\n+# public headers and source files so that we can tell doxygen which files to\n+# look at later. Unfortunately the inclusion of custom targets in some of the\n+# existing arrays precludes using them directly and you cannot generate File\n+# objects from generated files, so we need to collect paths to relevant files\n+# within an array.\n+doxygen_public_sources = []\n+\n subdir('include')\n subdir('src')\n \ndiff --git a/src/libcamera/base/class.cpp b/src/libcamera/base/class.cpp\nindex 61998398..b7ef3a1e 100644\n--- a/src/libcamera/base/class.cpp\n+++ b/src/libcamera/base/class.cpp\n@@ -184,6 +184,7 @@ Extensible::Extensible(std::unique_ptr d)\n */\n \n /**\n+ * \\internal\n * \\class Extensible::Private\n * \\brief Base class for private data managed through a d-pointer\n */\ndiff --git a/src/libcamera/base/meson.build b/src/libcamera/base/meson.build\nindex 523c5885..ae949a51 100644\n--- a/src/libcamera/base/meson.build\n+++ b/src/libcamera/base/meson.build\n@@ -30,6 +30,13 @@ libcamera_base_sources = [\n \tlibcamera_base_internal_sources\n ]\n \n+foreach lbps : libcamera_base_public_sources\n+\tdoxygen_public_sources += '/'.join(\n+\t\tmeson.project_source_root(),\n+\t\t'@0@'.format(lbps)\n+\t)\n+endforeach\n+\n libdw = dependency('libdw', required : false)\n libunwind = dependency('libunwind', required : false)\n \ndiff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp\nindex 67f34901..63285e2b 100644\n--- a/src/libcamera/camera.cpp\n+++ b/src/libcamera/camera.cpp\n@@ -560,6 +560,13 @@ CameraConfiguration::Status CameraConfiguration::validateColorSpaces(ColorSpaceF\n */\n \n /**\n+ * \\internal\n+ * \\file libcamera\\internal\\camera.h\n+ * \\brief Internal Camera device handling\n+ */\n+\n+/**\n+ * \\internal\n * \\class Camera::Private\n * \\brief Base class for camera private data\n *\ndiff --git a/src/libcamera/camera_manager.cpp b/src/libcamera/camera_manager.cpp\nindex 95a9e326..5a21132a 100644\n--- a/src/libcamera/camera_manager.cpp\n+++ b/src/libcamera/camera_manager.cpp\n@@ -23,6 +23,7 @@\n */\n \n /**\n+ * \\internal\n * \\file libcamera/internal/camera_manager.h\n * \\brief Internal camera manager support\n */\ndiff --git a/src/libcamera/framebuffer.cpp b/src/libcamera/framebuffer.cpp\nindex 63d679cb..0f8c8f9d 100644\n--- a/src/libcamera/framebuffer.cpp\n+++ b/src/libcamera/framebuffer.cpp\n@@ -16,7 +16,10 @@\n /**\n * \\file libcamera/framebuffer.h\n * \\brief Frame buffer handling\n- *\n+ */\n+\n+/**\n+ * \\internal\n * \\file libcamera/internal/framebuffer.h\n * \\brief Internal frame buffer handling support\n */\n@@ -105,6 +108,7 @@ LOG_DEFINE_CATEGORY(Buffer)\n */\n \n /**\n+ * \\internal\n * \\class FrameBuffer::Private\n * \\brief Base class for FrameBuffer private data\n *\ndiff --git a/src/libcamera/meson.build b/src/libcamera/meson.build\nindex 9c74241d..1cc24cdc 100644\n--- a/src/libcamera/meson.build\n+++ b/src/libcamera/meson.build\n@@ -59,6 +59,13 @@ libcamera_sources = [\n \tlibcamera_internal_sources\n ]\n \n+foreach lps : libcamera_public_sources\n+\tdoxygen_public_sources += '/'.join(\n+\t\tmeson.project_source_root(),\n+\t\t'@0@'.format(lps)\n+\t)\n+endforeach\n+\n libcamera_sources += libcamera_public_headers\n libcamera_sources += libcamera_generated_ipa_headers\n libcamera_sources += libcamera_tracepoint_header\ndiff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp\nindex cfb451e9..e8604121 100644\n--- a/src/libcamera/request.cpp\n+++ b/src/libcamera/request.cpp\n@@ -33,6 +33,7 @@ namespace libcamera {\n LOG_DEFINE_CATEGORY(Request)\n \n /**\n+ * \\internal\n * \\class Request::Private\n * \\brief Request private data\n *\n","prefixes":["v4","3/4"]}