From patchwork Thu Aug 8 14:09:44 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dan Scally X-Patchwork-Id: 20840 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id A2059C323E for ; Thu, 8 Aug 2024 14:10:10 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id C7433633BE; Thu, 8 Aug 2024 16:10:08 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="t3oc9lcG"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id E57496337F for ; Thu, 8 Aug 2024 16:10:04 +0200 (CEST) Received: from mail.ideasonboard.com (cpc141996-chfd3-2-0-cust928.12-3.cable.virginm.net [86.13.91.161]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 1559E15B7; Thu, 8 Aug 2024 16:09:11 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1723126151; bh=eq8MvdvIAvucag7Cc3TY2nXP6H7b8e0xUnvhvKkCrL0=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=t3oc9lcG+Cz8lM8TDpeS8yA5z/MHitNZ35JAKxLn7ZVMsHBtoGfQkEnd1oBQ5Uul7 ws5mGWBVHYBbjoK4sEZFEKuyUCqnsu5oHa7BaDUN/sez2/ax1jovBR/M8bVzYA6d2R X9EXaa2Saupy1tVro4biu2avU8qE7++8Xe1CsSQs= From: Daniel Scally To: libcamera-devel@lists.libcamera.org Cc: Daniel Scally Subject: [PATCH v7 1/5] Documentation: Add Thread safety page Date: Thu, 8 Aug 2024 15:09:44 +0100 Message-Id: <20240808140948.430419-2-dan.scally@ideasonboard.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240808140948.430419-1-dan.scally@ideasonboard.com> References: <20240808140948.430419-1-dan.scally@ideasonboard.com> MIME-Version: 1.0 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: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" Move the section of the Thread support page dealing with thread safety to a dedicated .dox file at Documentation/. This is done to support the splitting of the Documentation into a public and internal version. With a separate page, references can be made to thread safety without having to include the Thread class in the doxygen run. Some sections of the new page are still specific to internal implementations and so are hidden with the \internal flag and an internal section which is conditionally included. For now, hardcode it to be included in the Doxyfile. Signed-off-by: Daniel Scally Reviewed-by: Laurent Pinchart --- Changes since v6: Conditionally included any reference to thread-bound behind either the \internal directive or and internal section. Changes since v5: - Much of the content that dealt with internal implementation was moved back to its place against the Thread class. The thread safety section is retained in a separate page, with a single reference to the main thread support page who's display is conditional on the doxygen INTERNAL_DOCS directive. Given the scope of the changes, I dropped the R-b tags the patch had accumulated Changes since v1: - New patch Documentation/Doxyfile.in | 5 +++- Documentation/thread-safety.dox | 48 +++++++++++++++++++++++++++++++++ src/libcamera/base/thread.cpp | 36 ------------------------- 3 files changed, 52 insertions(+), 37 deletions(-) create mode 100644 Documentation/thread-safety.dox diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in index 62e63968..203f8e67 100644 --- a/Documentation/Doxyfile.in +++ b/Documentation/Doxyfile.in @@ -17,13 +17,15 @@ EXTENSION_MAPPING = h=C++ TOC_INCLUDE_HEADINGS = 0 +ENABLED_SECTIONS = internal INTERNAL_DOCS = YES CASE_SENSE_NAMES = YES QUIET = YES WARN_AS_ERROR = @WARN_AS_ERROR@ -INPUT = "@TOP_SRCDIR@/include/libcamera" \ +INPUT = "@TOP_SRCDIR@/Documentation" \ + "@TOP_SRCDIR@/include/libcamera" \ "@TOP_SRCDIR@/src/ipa/ipu3" \ "@TOP_SRCDIR@/src/ipa/libipa" \ "@TOP_SRCDIR@/src/libcamera" \ @@ -32,6 +34,7 @@ INPUT = "@TOP_SRCDIR@/include/libcamera" \ FILE_PATTERNS = *.c \ *.cpp \ + *.dox \ *.h RECURSIVE = YES diff --git a/Documentation/thread-safety.dox b/Documentation/thread-safety.dox new file mode 100644 index 00000000..1a610035 --- /dev/null +++ b/Documentation/thread-safety.dox @@ -0,0 +1,48 @@ +/** + * \page thread-safety Reentrancy and Thread-Safety + * + * Through the documentation, several terms are used to define how classes and + * their member functions can be used from multiple threads. + * + * - A **reentrant** function may be called simultaneously from multiple + * threads if and only if each invocation uses a different instance of the + * class. This is the default for all member functions not explictly marked + * otherwise. + * + * - \anchor thread-safe A **thread-safe** function may be called + * simultaneously from multiple threads on the same instance of a class. A + * thread-safe function is thus reentrant. Thread-safe functions may also be + * called simultaneously with any other reentrant function of the same class + * on the same instance. + * + * \internal + * - \anchor thread-bound A **thread-bound** function may be called only from + * the thread that the class instances lives in (see section \ref + * thread-objects). For instances of classes that do not derive from the + * Object class, this is the thread in which the instance was created. A + * thread-bound function is not thread-safe, and may or may not be reentrant. + * \endinternal + * + * Neither reentrancy nor thread-safety, in this context, mean that a function + * may be called simultaneously from the same thread, for instance from a + * callback invoked by the function. This may deadlock and isn't allowed unless + * separately documented. + * + * \if internal + * A class is defined as reentrant, thread-safe or thread-bound if all its + * member functions are reentrant, thread-safe or thread-bound respectively. + * Some member functions may additionally be documented as having additional + * thread-related attributes. + * + * \else + * + * A class is defined as reentrant or thread-safe if all its member functions + * are reentrant or thread-safe respectively. Some member functions may + * additionally be documented as having additional thread-related attributes. + * + * \endif + * + * Most classes are reentrant but not thread-safe, as making them fully + * thread-safe would incur locking costs considered prohibitive for the + * expected use cases. + */ diff --git a/src/libcamera/base/thread.cpp b/src/libcamera/base/thread.cpp index 72733431..8735670b 100644 --- a/src/libcamera/base/thread.cpp +++ b/src/libcamera/base/thread.cpp @@ -64,42 +64,6 @@ * receiver's event loop, running in the receiver's thread. This mechanism can * be overridden by selecting a different connection type when calling * Signal::connect(). - * - * \section thread-reentrancy Reentrancy and Thread-Safety - * - * Through the documentation, several terms are used to define how classes and - * their member functions can be used from multiple threads. - * - * - A **reentrant** function may be called simultaneously from multiple - * threads if and only if each invocation uses a different instance of the - * class. This is the default for all member functions not explictly marked - * otherwise. - * - * - \anchor thread-safe A **thread-safe** function may be called - * simultaneously from multiple threads on the same instance of a class. A - * thread-safe function is thus reentrant. Thread-safe functions may also be - * called simultaneously with any other reentrant function of the same class - * on the same instance. - * - * - \anchor thread-bound A **thread-bound** function may be called only from - * the thread that the class instances lives in (see section \ref - * thread-objects). For instances of classes that do not derive from the - * Object class, this is the thread in which the instance was created. A - * thread-bound function is not thread-safe, and may or may not be reentrant. - * - * Neither reentrancy nor thread-safety, in this context, mean that a function - * may be called simultaneously from the same thread, for instance from a - * callback invoked by the function. This may deadlock and isn't allowed unless - * separately documented. - * - * A class is defined as reentrant, thread-safe or thread-bound if all its - * member functions are reentrant, thread-safe or thread-bound respectively. - * Some member functions may additionally be documented as having additional - * thread-related attributes. - * - * Most classes are reentrant but not thread-safe, as making them fully - * thread-safe would incur locking costs considered prohibitive for the - * expected use cases. */ /** From patchwork Thu Aug 8 14:09:45 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dan Scally X-Patchwork-Id: 20841 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id B93C3C323E for ; Thu, 8 Aug 2024 14:10:12 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id 70C2E633C1; Thu, 8 Aug 2024 16:10:09 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="EVp5Fa6v"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 1F6F563382 for ; Thu, 8 Aug 2024 16:10:05 +0200 (CEST) Received: from mail.ideasonboard.com (cpc141996-chfd3-2-0-cust928.12-3.cable.virginm.net [86.13.91.161]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 567E115D6; Thu, 8 Aug 2024 16:09:11 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1723126151; bh=dFt9aFhN1NZl80HshdPn4pULD5quCsdHFMP6ydKySXI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=EVp5Fa6vKz8aZRpDSU20hQphiXn/4ectes6oTV0FvrJVh9/+z2dYRYTFQTVcnBDgE CwcO6do9/ELk/8aGVqhRbHNFpAr3LpmLBPt8vLzRT95tNne/dnonBzDgpklQtXnpOr a2ifQBGDzp1nCVCWC4ZPXghCUkbQJC2Z5lvd0ipA= From: Daniel Scally To: libcamera-devel@lists.libcamera.org Cc: Laurent Pinchart , Daniel Scally , Kieran Bingham Subject: [PATCH v7 2/5] Documentation: Split doxygen_input in public and internal inputs Date: Thu, 8 Aug 2024 15:09:45 +0100 Message-Id: <20240808140948.430419-3-dan.scally@ideasonboard.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240808140948.430419-1-dan.scally@ideasonboard.com> References: <20240808140948.430419-1-dan.scally@ideasonboard.com> MIME-Version: 1.0 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: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" From: Laurent Pinchart To prepare for splitting the API documentation in public and internal documents, split the doxygen_input list in the public and internal counterparts. Signed-off-by: Laurent Pinchart Reviewed-by: Daniel Scally Reviewed-by: Kieran Bingham --- Changes since v6: None Documentation/meson.build | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/Documentation/meson.build b/Documentation/meson.build index 07042071..1d84ed81 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -28,27 +28,34 @@ if doxygen.found() and dot.found() output : 'Doxyfile', configuration : cdata) - doxygen_input = [ - doxyfile, - libcamera_base_headers, + doxygen_public_input = [ + libcamera_base_public_headers, libcamera_base_public_sources, + libcamera_public_headers, + libcamera_public_sources, + ] + + doxygen_internal_input = [ + libcamera_base_private_headers, libcamera_base_internal_sources, libcamera_internal_headers, + libcamera_internal_sources, libcamera_ipa_headers, libcamera_ipa_interfaces, - libcamera_public_headers, - libcamera_public_sources, - libcamera_internal_sources, libipa_headers, libipa_sources, ] if is_variable('ipu3_ipa_sources') - doxygen_input += [ipu3_ipa_sources] + doxygen_internal_input += [ipu3_ipa_sources] endif custom_target('doxygen', - input : doxygen_input, + input : [ + doxyfile, + doxygen_public_input, + doxygen_internal_input, + ], output : 'api-html', command : [doxygen, doxyfile], install : true, From patchwork Thu Aug 8 14:09:46 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dan Scally X-Patchwork-Id: 20842 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id EB7A0C324E for ; Thu, 8 Aug 2024 14:10:13 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id E509863398; Thu, 8 Aug 2024 16:10:10 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="YDGYcdNp"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id 4944A6338D for ; Thu, 8 Aug 2024 16:10:05 +0200 (CEST) Received: from mail.ideasonboard.com (cpc141996-chfd3-2-0-cust928.12-3.cable.virginm.net [86.13.91.161]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id A91E513D7; Thu, 8 Aug 2024 16:09:11 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1723126151; bh=NOGj+Pd28BPikw2fPi+QQILJCyTMEEVk9BNb4Clp2yI=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=YDGYcdNpRujoUrNwn0M9xgPXEl6XhdmzjZJDswezGs8i14eM4sf2GQn9bvW5yg/pr KNV0TRQx/6VHJMr1usypmOTDyJIIKX3HXnrnal0lj4PCb0S+uZe8UFx3SAvUwnVFT8 3CMzaiCC7da3g4ay1fKqGpiUzliwqe2vpXdqYwvU= From: Daniel Scally To: libcamera-devel@lists.libcamera.org Cc: Daniel Scally , Laurent Pinchart , Kieran Bingham Subject: [PATCH v7 3/5] Documentation: Split public/private documentation Date: Thu, 8 Aug 2024 15:09:46 +0100 Message-Id: <20240808140948.430419-4-dan.scally@ideasonboard.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240808140948.430419-1-dan.scally@ideasonboard.com> References: <20240808140948.430419-1-dan.scally@ideasonboard.com> MIME-Version: 1.0 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: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" The API reference pages generated by Doxygen are comprehensive, but therefore quite overwhelming for application developers who will likely never need to use the majority of the library's objects. To reduce the complexity of the documentation, split it into two runs of doxygen. The first run of doxygen is for the public API. We pass a specific list of source files to parse, which is built from the arrays of public headers and sources in meson build files. This ensures that we only generate the documentation for code from those files. A custom Python script is needed to add the list of input files to Doxyfile, as several of the objects included in the header and source array are custom_tgt objects, which can't be handled as strings to populate a variable in the configuration data. The headers defining the Extensible and Object classes (class.h and object.h respectively), as well as the corresponding source files, are excluded from the public API documentation despite being referenced in the meson public headers and sources arrays. This is due to the fact that public API classes inherit from Extensible and Object, making the Extensible and Object classes part of the public ABI. Those two base classes are however implementation details and must not be accessed directly by application code. The second run of doxygen is for the internal API. This contains documentation for all of the library's objects as it currently does. This set will now be output into build/Documentation/internal-api-html. Signed-off-by: Daniel Scally Co-developed-by: Laurent Pinchart Signed-off-by: Laurent Pinchart Reviewed-by: Kieran Bingham Reviewed-by: Daniel Scally --- Changes since v6: None .../{Doxyfile.in => Doxyfile-common.in} | 25 -------- Documentation/Doxyfile-internal.in | 31 ++++++++++ Documentation/Doxyfile-public.in | 20 ++++++ Documentation/gen-doxyfile.py | 46 ++++++++++++++ Documentation/meson.build | 61 +++++++++++++++++-- 5 files changed, 152 insertions(+), 31 deletions(-) rename Documentation/{Doxyfile.in => Doxyfile-common.in} (61%) create mode 100644 Documentation/Doxyfile-internal.in create mode 100644 Documentation/Doxyfile-public.in create mode 100755 Documentation/gen-doxyfile.py diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile-common.in similarity index 61% rename from Documentation/Doxyfile.in rename to Documentation/Doxyfile-common.in index 203f8e67..a70aee43 100644 --- a/Documentation/Doxyfile.in +++ b/Documentation/Doxyfile-common.in @@ -17,21 +17,11 @@ EXTENSION_MAPPING = h=C++ TOC_INCLUDE_HEADINGS = 0 -ENABLED_SECTIONS = internal -INTERNAL_DOCS = YES CASE_SENSE_NAMES = YES QUIET = YES WARN_AS_ERROR = @WARN_AS_ERROR@ -INPUT = "@TOP_SRCDIR@/Documentation" \ - "@TOP_SRCDIR@/include/libcamera" \ - "@TOP_SRCDIR@/src/ipa/ipu3" \ - "@TOP_SRCDIR@/src/ipa/libipa" \ - "@TOP_SRCDIR@/src/libcamera" \ - "@TOP_BUILDDIR@/include/libcamera" \ - "@TOP_BUILDDIR@/src/libcamera" - FILE_PATTERNS = *.c \ *.cpp \ *.dox \ @@ -39,19 +29,6 @@ FILE_PATTERNS = *.c \ RECURSIVE = YES -EXCLUDE = @TOP_SRCDIR@/include/libcamera/base/span.h \ - @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_sysfs.h \ - @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_udev.h \ - @TOP_SRCDIR@/include/libcamera/internal/ipc_pipe_unixsocket.h \ - @TOP_SRCDIR@/src/libcamera/device_enumerator_sysfs.cpp \ - @TOP_SRCDIR@/src/libcamera/device_enumerator_udev.cpp \ - @TOP_SRCDIR@/src/libcamera/ipc_pipe_unixsocket.cpp \ - @TOP_SRCDIR@/src/libcamera/pipeline/ \ - @TOP_SRCDIR@/src/libcamera/tracepoints.cpp \ - @TOP_BUILDDIR@/include/libcamera/internal/tracepoints.h \ - @TOP_BUILDDIR@/include/libcamera/ipa/soft_ipa_interface.h \ - @TOP_BUILDDIR@/src/libcamera/proxy/ - EXCLUDE_PATTERNS = @TOP_BUILDDIR@/include/libcamera/ipa/*_serializer.h \ @TOP_BUILDDIR@/include/libcamera/ipa/*_proxy.h \ @TOP_BUILDDIR@/include/libcamera/ipa/ipu3_*.h \ @@ -74,8 +51,6 @@ EXCLUDE_SYMBOLS = libcamera::BoundMethodArgs \ EXCLUDE_SYMLINKS = YES -HTML_OUTPUT = api-html - GENERATE_LATEX = NO MACRO_EXPANSION = YES diff --git a/Documentation/Doxyfile-internal.in b/Documentation/Doxyfile-internal.in new file mode 100644 index 00000000..cf982553 --- /dev/null +++ b/Documentation/Doxyfile-internal.in @@ -0,0 +1,31 @@ +# SPDX-License-Identifier: CC-BY-SA-4.0 + +@INCLUDE_PATH = @TOP_BUILDDIR@/Documentation +@INCLUDE = Doxyfile-common + +HIDE_UNDOC_CLASSES = NO +HIDE_UNDOC_MEMBERS = NO +HTML_OUTPUT = internal-api-html +INTERNAL_DOCS = YES +ENABLED_SECTIONS = internal + +INPUT = "@TOP_SRCDIR@/Documentation" \ + "@TOP_SRCDIR@/include/libcamera" \ + "@TOP_SRCDIR@/src/ipa/ipu3" \ + "@TOP_SRCDIR@/src/ipa/libipa" \ + "@TOP_SRCDIR@/src/libcamera" \ + "@TOP_BUILDDIR@/include/libcamera" \ + "@TOP_BUILDDIR@/src/libcamera" + +EXCLUDE = @TOP_SRCDIR@/include/libcamera/base/span.h \ + @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_sysfs.h \ + @TOP_SRCDIR@/include/libcamera/internal/device_enumerator_udev.h \ + @TOP_SRCDIR@/include/libcamera/internal/ipc_pipe_unixsocket.h \ + @TOP_SRCDIR@/src/libcamera/device_enumerator_sysfs.cpp \ + @TOP_SRCDIR@/src/libcamera/device_enumerator_udev.cpp \ + @TOP_SRCDIR@/src/libcamera/ipc_pipe_unixsocket.cpp \ + @TOP_SRCDIR@/src/libcamera/pipeline/ \ + @TOP_SRCDIR@/src/libcamera/tracepoints.cpp \ + @TOP_BUILDDIR@/include/libcamera/internal/tracepoints.h \ + @TOP_BUILDDIR@/include/libcamera/ipa/soft_ipa_interface.h \ + @TOP_BUILDDIR@/src/libcamera/proxy/ diff --git a/Documentation/Doxyfile-public.in b/Documentation/Doxyfile-public.in new file mode 100644 index 00000000..36bb5758 --- /dev/null +++ b/Documentation/Doxyfile-public.in @@ -0,0 +1,20 @@ +# SPDX-License-Identifier: CC-BY-SA-4.0 + +@INCLUDE_PATH = @TOP_BUILDDIR@/Documentation +@INCLUDE = Doxyfile-common + +HIDE_UNDOC_CLASSES = YES +HIDE_UNDOC_MEMBERS = YES +HTML_OUTPUT = api-html +INTERNAL_DOCS = NO + +INPUT = "@TOP_SRCDIR@/Documentation" \ + ${inputs} + +EXCLUDE = @TOP_SRCDIR@/include/libcamera/base/class.h \ + @TOP_SRCDIR@/include/libcamera/base/object.h \ + @TOP_SRCDIR@/include/libcamera/base/span.h \ + @TOP_SRCDIR@/src/libcamera/base/class.cpp \ + @TOP_SRCDIR@/src/libcamera/base/object.cpp + +PREDEFINED += __DOXYGEN_PUBLIC__ diff --git a/Documentation/gen-doxyfile.py b/Documentation/gen-doxyfile.py new file mode 100755 index 00000000..c265bc2f --- /dev/null +++ b/Documentation/gen-doxyfile.py @@ -0,0 +1,46 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: GPL-2.0-or-later +# Copyright (C) 2024, Google Inc. +# +# Author: Laurent Pinchart +# +# Generate Doxyfile from a template + +import argparse +import os +import string +import sys + + +def fill_template(template, data): + + template = open(template, 'rb').read() + template = template.decode('utf-8') + template = string.Template(template) + + return template.substitute(data) + + +def main(argv): + + parser = argparse.ArgumentParser() + parser.add_argument('-o', dest='output', metavar='file', + type=argparse.FileType('w', encoding='utf-8'), + default=sys.stdout, + help='Output file name (default: standard output)') + parser.add_argument('template', metavar='doxyfile.tmpl', type=str, + help='Doxyfile template') + parser.add_argument('inputs', type=str, nargs='*', + help='Input files') + + args = parser.parse_args(argv[1:]) + + inputs = [f'"{os.path.realpath(input)}"' for input in args.inputs] + data = fill_template(args.template, {'inputs': (' \\\n' + ' ' * 25).join(inputs)}) + args.output.write(data) + + return 0 + + +if __name__ == '__main__': + sys.exit(main(sys.argv)) diff --git a/Documentation/meson.build b/Documentation/meson.build index 1d84ed81..1ba40fdf 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -24,9 +24,9 @@ if doxygen.found() and dot.found() cdata.set('PREDEFINED', ' \\\n\t\t\t '.join(doxygen_predefined)) - doxyfile = configure_file(input : 'Doxyfile.in', - output : 'Doxyfile', - configuration : cdata) + doxyfile_common = configure_file(input : 'Doxyfile-common.in', + output : 'Doxyfile-common', + configuration : cdata) doxygen_public_input = [ libcamera_base_public_headers, @@ -50,17 +50,66 @@ if doxygen.found() and dot.found() doxygen_internal_input += [ipu3_ipa_sources] endif - custom_target('doxygen', + # We run doxygen twice - the first run excludes internal API objects as it + # is intended to document the public API only. A second run covers all of + # the library's objects for libcamera developers. Common configuration is + # set in an initially generated Doxyfile, which is then included by the two + # final Doxyfiles. + + # This is the "public" run of doxygen generating an abridged version of the + # API's documentation. + + doxyfile_tmpl = configure_file(input : 'Doxyfile-public.in', + output : 'Doxyfile-public.tmpl', + configuration : cdata) + + # The set of public input files stored in the doxygen_public_input array + # needs to be set in Doxyfile public. We can't pass them through cdata + # cdata, as some of the array members are custom_tgt instances, which + # configuration_data.set() doesn't support. Using a separate script invoked + # through custom_target(), which supports custom_tgt instances as inputs. + + doxyfile = custom_target('doxyfile-public', + input : [ + doxygen_public_input, + ], + output : 'Doxyfile-public', + command : [ + 'gen-doxyfile.py', + '-o', '@OUTPUT@', + doxyfile_tmpl, + '@INPUT@', + ]) + + custom_target('doxygen-public', input : [ doxyfile, - doxygen_public_input, - doxygen_internal_input, + doxyfile_common, ], output : 'api-html', command : [doxygen, doxyfile], install : true, install_dir : doc_install_dir, install_tag : 'doc') + + # This is the internal documentation, which hard-codes a list of directories + # to parse in its doxyfile. + + doxyfile = configure_file(input : 'Doxyfile-internal.in', + output : 'Doxyfile-internal', + configuration : cdata) + + custom_target('doxygen-internal', + input : [ + doxyfile, + doxyfile_common, + doxygen_internal_input, + ], + output : 'internal-api-html', + command : [doxygen, doxyfile], + install : true, + install_dir : doc_install_dir, + install_tag : 'doc-internal') endif # From patchwork Thu Aug 8 14:09:47 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dan Scally X-Patchwork-Id: 20843 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id E886FC323E for ; Thu, 8 Aug 2024 14:10:14 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id D52FC633B4; Thu, 8 Aug 2024 16:10:12 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="v/ieX1F9"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id A0740633AC for ; Thu, 8 Aug 2024 16:10:05 +0200 (CEST) Received: from mail.ideasonboard.com (cpc141996-chfd3-2-0-cust928.12-3.cable.virginm.net [86.13.91.161]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 08B4815B7; Thu, 8 Aug 2024 16:09:11 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1723126152; bh=5inPCLTTh+y1N5mpOH/gWa8RojONc4VZ+jtAoBx5vAM=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=v/ieX1F9FwNQPOkoiZQrg/GfQYgCNiSTeHlyfPw7BdOXJS9yESrggHADfOwg/YJ6V 82Vn2C1BeYyxxm4FVo+Kbo2o91R7SFIx4Kd/tAO4b+xTd+W/COoPqA8TBYtWMnsgs4 NiSnfYtz8lhG/C/K313u0C9aql/ZSxcDPHMnn45Y= From: Daniel Scally To: libcamera-devel@lists.libcamera.org Cc: Daniel Scally , Jacopo Mondi , Kieran Bingham Subject: [PATCH v7 4/5] Documentation: Improve doxygen main page Date: Thu, 8 Aug 2024 15:09:47 +0100 Message-Id: <20240808140948.430419-5-dan.scally@ideasonboard.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240808140948.430419-1-dan.scally@ideasonboard.com> References: <20240808140948.430419-1-dan.scally@ideasonboard.com> MIME-Version: 1.0 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: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" The "Main Page" of the doxygen generated API reference is currently totally empty. Expand it with some introductory text along with links to the developer's guide, application developer's guide and the pipeline and IPA module writer's guides. Provide an easy link to switch between the reduced public reference pages and the more complete internal ones. Reviewed-by: Jacopo Mondi Reviewed-by: Kieran Bingham Signed-off-by: Daniel Scally Reviewed-by: Laurent Pinchart --- Changes since v6: - Addressed knock-on effect of patch #1 changes - no need to set the ENABLED_SECTIONS in Doxyfiles anymore, as it was already done. Documentation/mainpage.dox | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 Documentation/mainpage.dox diff --git a/Documentation/mainpage.dox b/Documentation/mainpage.dox new file mode 100644 index 00000000..d5a57653 --- /dev/null +++ b/Documentation/mainpage.dox @@ -0,0 +1,33 @@ +/** +\mainpage libcamera API reference + +Welcome to the API reference for libcamera, +a complex camera support library for Linux, Android and ChromeOS. These pages +are automatically generated from the libcamera source code and describe the API +in detail - if this is your first interaction with libcamera then you may find +it useful to visit the [developer's guide](../html/guides/introduction.html) in +the first instance, which can provide a more generic introduction to the +library's concepts. + +\if internal + +As a follow-on to the developer's guide, to assist you in adding support for +your platform the [pipeline handler writer's guide](../html/guides/pipeline-handler.html) +and the [ipa module writer's guide](../html/guides/ipa.html) should be helpful. + +The full libcamera API is documented here. If you wish to see only the public +part of the API you can use [these pages](../api-html/index.html) instead. + +\else + +As a follow-on to the developer's guide, to assist you in using libcamera within +your project the [application developer's guide](../html/guides/application-developer.html) +gives an overview on how to achieve that. + +Only the public part of the libcamera API is documented here; if you are a +developer seeking to add support for your hardware to the library or make other +improvements, you should switch to the internal API +[reference pages](../internal-api-html/index.html) instead. + +\endif +*/ From patchwork Thu Aug 8 14:09:48 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dan Scally X-Patchwork-Id: 20844 Return-Path: X-Original-To: parsemail@patchwork.libcamera.org Delivered-To: parsemail@patchwork.libcamera.org Received: from lancelot.ideasonboard.com (lancelot.ideasonboard.com [92.243.16.209]) by patchwork.libcamera.org (Postfix) with ESMTPS id B9765C32D5 for ; Thu, 8 Aug 2024 14:10:15 +0000 (UTC) Received: from lancelot.ideasonboard.com (localhost [IPv6:::1]) by lancelot.ideasonboard.com (Postfix) with ESMTP id A8A13633BD; Thu, 8 Aug 2024 16:10:13 +0200 (CEST) Authentication-Results: lancelot.ideasonboard.com; dkim=pass (1024-bit key; unprotected) header.d=ideasonboard.com header.i=@ideasonboard.com header.b="cdXWJQDA"; dkim-atps=neutral Received: from perceval.ideasonboard.com (perceval.ideasonboard.com [213.167.242.64]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id EB26261955 for ; Thu, 8 Aug 2024 16:10:05 +0200 (CEST) Received: from mail.ideasonboard.com (cpc141996-chfd3-2-0-cust928.12-3.cable.virginm.net [86.13.91.161]) by perceval.ideasonboard.com (Postfix) with ESMTPSA id 5A59A1648; Thu, 8 Aug 2024 16:09:12 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com; s=mail; t=1723126152; bh=iWC5leEoJr3surrVUwowe34p3yWYic+q7VhXfvX9DfE=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=cdXWJQDANcT5Hg2rYKpatj6MS0mlnpaSQgyoy2mXzq6EjIEcsJz5Bchw53b18SDeX v9ttCdH3J9o/ieWML13RNnfnzOHDX8j5ha8S0pOlE1AoY4xduJ6b1uLQu6+jsWhpxz H2/DYcWkerv+RLndwON92hWyWK50npZoKQaWCGQc= From: Daniel Scally To: libcamera-devel@lists.libcamera.org Cc: Laurent Pinchart , Kieran Bingham , Daniel Scally Subject: [PATCH v7 5/5] libcamera: camera: Hide Camera::create() from the public API Date: Thu, 8 Aug 2024 15:09:48 +0100 Message-Id: <20240808140948.430419-6-dan.scally@ideasonboard.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20240808140948.430419-1-dan.scally@ideasonboard.com> References: <20240808140948.430419-1-dan.scally@ideasonboard.com> MIME-Version: 1.0 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: , Errors-To: libcamera-devel-bounces@lists.libcamera.org Sender: "libcamera-devel" From: Laurent Pinchart The Camera::create() function is internal. Hide it from the public API documentation. Signed-off-by: Laurent Pinchart Reviewed-by: Kieran Bingham Reviewed-by: Daniel Scally --- Changes since v6: None src/libcamera/camera.cpp | 1 + 1 file changed, 1 insertion(+) diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp index aca466c9..382a68f7 100644 --- a/src/libcamera/camera.cpp +++ b/src/libcamera/camera.cpp @@ -821,6 +821,7 @@ void Camera::Private::setState(State state) */ /** + * \internal * \brief Create a camera instance * \param[in] d Camera private data * \param[in] id The ID of the camera device