ipa: Move core IPA interface documentation to a .cpp file

Moving the core.mojom documentation to its corresponding .cpp file
(core_ipa_interface.cpp). This will allow Doxygen to generate the
documentation for IPABuffer, IPASettings and IPAStream structures.
Since the .mojom files are placed in include/ directory, the .cpp file
will live in $sourcedir/src/libcamera/ipa/ - which can also contain
documentation for other mojom generated IPA interfaces in subsequent
commit.

Also hide the constructors in generated IPA interface from doxygen,
via  #ifndef __DOXYGEN__. These constructors provide no major value in
documenting them, instead will spew out doxygen warnings during the
build.

Signed-off-by: Umang Jain <umang.jain@ideasonboard.com>
Acked-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Paul Elder <paul.elder@ideasonboard.com>
Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

Documentation/Doxyfile.in

@@ -844,7 +844,6 @@ EXCLUDE                = @TOP_SRCDIR@/include/libcamera/span.h \
 			 @TOP_SRCDIR@/src/libcamera/pipeline/ \
 			 @TOP_SRCDIR@/src/libcamera/tracepoints.cpp \
 			 @TOP_BUILDDIR@/include/libcamera/internal/tracepoints.h \
-			 @TOP_BUILDDIR@/include/libcamera/ipa/ \
 			 @TOP_BUILDDIR@/src/libcamera/proxy/
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
@@ -861,7 +860,12 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       =
+EXCLUDE_PATTERNS       = @TOP_BUILDDIR@/include/libcamera/ipa/*_serializer.h \
+                         @TOP_BUILDDIR@/include/libcamera/ipa/*_proxy.h \
+                         @TOP_BUILDDIR@/include/libcamera/ipa/ipu3_*.h \
+                         @TOP_BUILDDIR@/include/libcamera/ipa/raspberrypi_*.h \
+                         @TOP_BUILDDIR@/include/libcamera/ipa/rkisp1_*.h \
+                         @TOP_BUILDDIR@/include/libcamera/ipa/vimc_*.h \
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the

Documentation/meson.build

@@ -24,6 +24,7 @@ if doxygen.found() and dot.found()
                       doxyfile,
                       libcamera_internal_headers,
                       libcamera_ipa_headers,
+                      libcamera_ipa_interfaces,
                       libcamera_public_headers,
                       libcamera_sources,
                       libipa_headers,

include/libcamera/ipa/core.mojom

@@ -94,88 +94,16 @@ module libcamera;
 	uint32 maxFrameLength;
 };
 
-/**
- * \struct IPABuffer
- * \brief Buffer information for the IPA interface
- *
- * The IPABuffer structure associates buffer memory with a unique ID. It is
- * used to map buffers to the IPA with IPAInterface::mapBuffers(), after which
- * buffers will be identified by their ID in the IPA interface.
- */
-
-/**
- * \var IPABuffer::id
- * \brief The buffer unique ID
- *
- * Buffers mapped to the IPA are identified by numerical unique IDs. The IDs
- * are chosen by the pipeline handler to fulfil the following constraints:
- *
- * - IDs shall be positive integers different than zero
- * - IDs shall be unique among all mapped buffers
- *
- * When buffers are unmapped with IPAInterface::unmapBuffers() their IDs are
- * freed and may be reused for new buffer mappings.
- */
-
-/**
- * \var IPABuffer::planes
- * \brief The buffer planes description
- *
- * Stores the dmabuf handle and length for each plane of the buffer.
- */
-
 struct IPABuffer {
 	uint32 id;
 	[hasFd] array<FrameBuffer.Plane> planes;
 };
 
-/**
- * \struct IPASettings
- * \brief IPA interface initialization settings
- *
- * The IPASettings structure stores data passed to the IPAInterface::init()
- * function. The data contains settings that don't depend on a particular camera
- * or pipeline configuration and are valid for the whole life time of the IPA
- * interface.
- */
-
-/**
- * \var IPASettings::configurationFile
- * \brief The name of the IPA configuration file
- *
- * This field may be an empty string if the IPA doesn't require a configuration
- * file.
- */
-
- /**
- * \var IPASettings::sensorModel
- * \brief The sensor model name
- *
- * Provides the sensor model name to the IPA.
- */
 struct IPASettings {
 	string configurationFile;
 	string sensorModel;
 };
 
-/**
- * \struct IPAStream
- * \brief Stream configuration for the IPA interface
- *
- * The IPAStream structure stores stream configuration parameters needed by the
- * IPAInterface::configure() method. It mirrors the StreamConfiguration class
- * that is not suitable for this purpose due to not being serializable.
- */
-
-/**
- * \var IPAStream::pixelFormat
- * \brief The stream pixel format
- */
-
-/**
- * \var IPAStream::size
- * \brief The stream size in pixels
- */
 struct IPAStream {
 	uint32 pixelFormat;
 	Size size;

include/libcamera/ipa/ipu3.mojom

@@ -1,5 +1,10 @@
 /* SPDX-License-Identifier: LGPL-2.1-or-later */
 
+/*
+ * \todo Document the interface as src/libcamera/ipa/ipu3_ipa_interface.cpp
+ * and remove the EXCLUDE_PATTERNS entry in Doxygen.in for its generation.
+ */
+
 module ipa.ipu3;
 
 import "include/libcamera/ipa/core.mojom";

include/libcamera/ipa/raspberrypi.mojom

@@ -1,5 +1,10 @@
 /* SPDX-License-Identifier: LGPL-2.1-or-later */
 
+/*
+ * \todo Document the interface as src/libcamera/ipa/raspberrypi_ipa_interface.cpp
+ * and remove the EXCLUDE_PATTERNS entry in Doxygen.in for its generation.
+ */
+
 module ipa.RPi;
 
 import "include/libcamera/ipa/core.mojom";

include/libcamera/ipa/rkisp1.mojom

@@ -1,5 +1,10 @@
 /* SPDX-License-Identifier: LGPL-2.1-or-later */
 
+/*
+ * \todo Document the interface as src/libcamera/ipa/rkisp1_ipa_interface.cpp
+ * and remove the EXCLUDE_PATTERNS entry in Doxygen.in for its generation.
+ */
+
 module ipa.rkisp1;
 
 import "include/libcamera/ipa/core.mojom";

include/libcamera/ipa/vimc.mojom

@@ -1,5 +1,10 @@
 /* SPDX-License-Identifier: LGPL-2.1-or-later */
 
+/*
+ * \todo Document the interface as src/libcamera/ipa/vimc_ipa_interface.cpp
+ * and remove the EXCLUDE_PATTERNS entry in Doxygen.in for its generation.
+ */
+
 module ipa.vimc;
 
 import "include/libcamera/ipa/core.mojom";

src/libcamera/ipa/core_ipa_interface.cpp

@@ -0,0 +1,89 @@
+/* SPDX-License-Identifier: LGPL-2.1-or-later */
+/*
+ * Copyright (C) 2021, Google Inc.
+ *
+ * core_ipa_interface.cpp - Docs file for core.mojom generated header
+ */
+
+namespace libcamera {
+
+/**
+ * \file core_ipa_interface.h
+ * \brief Core IPA inteface
+ */
+
+/**
+ * \struct IPABuffer
+ * \brief Buffer information for the IPA interface
+ *
+ * The IPABuffer structure associates buffer memory with a unique ID. It is
+ * used to map buffers to the IPA with IPAInterface::mapBuffers(), after which
+ * buffers will be identified by their ID in the IPA interface.
+ */
+
+/**
+ * \var IPABuffer::id
+ * \brief The buffer unique ID
+ *
+ * Buffers mapped to the IPA are identified by numerical unique IDs. The IDs
+ * are chosen by the pipeline handler to fulfil the following constraints:
+ *
+ * - IDs shall be positive integers different than zero
+ * - IDs shall be unique among all mapped buffers
+ *
+ * When buffers are unmapped with IPAInterface::unmapBuffers() their IDs are
+ * freed and may be reused for new buffer mappings.
+ */
+
+/**
+ * \var IPABuffer::planes
+ * \brief The buffer planes description
+ *
+ * Stores the dmabuf handle and length for each plane of the buffer.
+ */
+
+/**
+ * \struct IPASettings
+ * \brief IPA interface initialization settings
+ *
+ * The IPASettings structure stores data passed to the IPAInterface::init()
+ * function. The data contains settings that don't depend on a particular camera
+ * or pipeline configuration and are valid for the whole life time of the IPA
+ * interface.
+ */
+
+/**
+ * \var IPASettings::configurationFile
+ * \brief The name of the IPA configuration file
+ *
+ * This field may be an empty string if the IPA doesn't require a configuration
+ * file.
+ */
+
+/**
+ * \var IPASettings::sensorModel
+ * \brief The sensor model name
+ *
+ * Provides the sensor model name to the IPA.
+ */
+
+/**
+ * \struct IPAStream
+ * \brief Stream configuration for the IPA interface
+ *
+ * The IPAStream structure stores stream configuration parameters needed by the
+ * IPAInterface::configure() method. It mirrors the StreamConfiguration class
+ * that is not suitable for this purpose due to not being serializable.
+ */
+
+/**
+ * \var IPAStream::pixelFormat
+ * \brief The stream pixel format
+ */
+
+/**
+ * \var IPAStream::size
+ * \brief The stream size in pixels
+ */
+
+} /* namespace libcamera */

src/libcamera/ipa/meson.build

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: CC0-1.0
+
+libcamera_ipa_interfaces = files([
+    'core_ipa_interface.cpp',
+])

src/libcamera/meson.build

@@ -66,6 +66,7 @@ includes = [
     libcamera_includes,
 ]
 
+subdir('ipa')
 subdir('pipeline')
 subdir('proxy')
 

utils/ipc/generators/libcamera_templates/definition_functions.tmpl

@@ -25,6 +25,7 @@ enum {{enum.mojom_name}} {
 struct {{struct.mojom_name}}
 {
 public:
+#ifndef __DOXYGEN__
 	{{struct.mojom_name}}() {%- if struct|has_default_fields %}
 		:{% endif %}
 {%- for field in struct.fields|with_default_values -%}
@@ -44,6 +45,8 @@ public:
 {%- endfor %}
 	{
 	}
+#endif
+
 {% for field in struct.fields %}
 	{{field|name}} {{field.mojom_name}};
 {%- endfor %}