[{"id":30642,"web_url":"https://patchwork.libcamera.org/comment/30642/","msgid":"<172300779879.1507574.13584029383654536681@ping.linuxembedded.co.uk>","date":"2024-08-07T05:16:38","subject":"Re: [PATCH v5 05/18] libcamera: Hide *::Private classes with\n\t__DOXYGEN_PUBLIC__","submitter":{"id":4,"url":"https://patchwork.libcamera.org/api/people/4/","name":"Kieran Bingham","email":"kieran.bingham@ideasonboard.com"},"content":"Quoting Laurent Pinchart (2024-08-05 15:36:41)\n> The *::Private classes are part of the internal API, as their name\n> implies. They are defined in internal headers, but implemented in the\n> same source file as their public counterparts. This will cause Doxygen\n> to complain about missing class definition when splitting the public and\n> internal API documents, as the internal headers won't be parsed by\n> Doxygen for the public API documentation.\n> \n> Marking the classes with \\internal isn't enough. The directive prevents\n> the documentation block from being included in the output, but this\n\nDoes \\private or \\privatesection do anything here? or does that still\nlead to the same issue as it will just mark them as 'private' and still\nexpect to find the definitions?\n\n> occurs at the generation stage, after the documentation blocks are\n> parsed. Fix this by completely hidding the implementation of the\n> *::Private classes from Doxygen using preprocessor conditional\n> compilation. To do so, introduce a new macro, __DOXYGEN_PUBLIC__, that\n> will be defined for the public API documentation only.\n\nIt's a shame to be adding ifdefery. But understandable if this is the\nbest way forwards.\n\nReviewed-by: Kieran Bingham \n> \n> Signed-off-by: Laurent Pinchart \n> ---\n> src/libcamera/camera.cpp | 2 ++\n> src/libcamera/camera_manager.cpp | 2 ++\n> src/libcamera/framebuffer.cpp | 2 ++\n> src/libcamera/request.cpp | 2 ++\n> 4 files changed, 8 insertions(+)\n> \n> diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp\n> index 3c8f30d54401..aca466c9ba72 100644\n> --- a/src/libcamera/camera.cpp\n> +++ b/src/libcamera/camera.cpp\n> @@ -565,6 +565,7 @@ CameraConfiguration::Status CameraConfiguration::validateColorSpaces(ColorSpaceF\n> * \\brief The vector of stream configurations\n> */\n> \n> +#ifndef __DOXYGEN_PUBLIC__\n> /**\n> * \\class Camera::Private\n> * \\brief Base class for camera private data\n> @@ -725,6 +726,7 @@ void Camera::Private::setState(State state)\n> {\n> state_.store(state, std::memory_order_release);\n> }\n> +#endif /* __DOXYGEN_PUBLIC__ */\n> \n> /**\n> * \\class Camera\n> diff --git a/src/libcamera/camera_manager.cpp b/src/libcamera/camera_manager.cpp\n> index 5a21132a08c2..fa44e33a135d 100644\n> --- a/src/libcamera/camera_manager.cpp\n> +++ b/src/libcamera/camera_manager.cpp\n> @@ -35,6 +35,7 @@ namespace libcamera {\n> \n> LOG_DEFINE_CATEGORY(Camera)\n> \n> +#ifndef __DOXYGEN_PUBLIC__\n> CameraManager::Private::Private()\n> : initialized_(false)\n> {\n> @@ -249,6 +250,7 @@ void CameraManager::Private::removeCamera(std::shared_ptr camera)\n> CameraManager *const o = LIBCAMERA_O_PTR();\n> o->cameraRemoved.emit(camera);\n> }\n> +#endif /* __DOXYGEN_PUBLIC__ */\n> \n> /**\n> * \\class CameraManager\n> diff --git a/src/libcamera/framebuffer.cpp b/src/libcamera/framebuffer.cpp\n> index f39db1223432..826848f75a56 100644\n> --- a/src/libcamera/framebuffer.cpp\n> +++ b/src/libcamera/framebuffer.cpp\n> @@ -107,6 +107,7 @@ LOG_DEFINE_CATEGORY(Buffer)\n> * \\return The array of per-plane metadata\n> */\n> \n> +#ifndef __DOXYGEN_PUBLIC__\n> /**\n> * \\class FrameBuffer::Private\n> * \\brief Base class for FrameBuffer private data\n> @@ -209,6 +210,7 @@ FrameBuffer::Private::~Private()\n> * \\brief Retrieve the dynamic metadata\n> * \\return Dynamic metadata for the frame contained in the buffer\n> */\n> +#endif /* __DOXYGEN_PUBLIC__ */\n> \n> /**\n> * \\class FrameBuffer\n> diff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp\n> index 24fa3a57312e..8c56ed30d0c4 100644\n> --- a/src/libcamera/request.cpp\n> +++ b/src/libcamera/request.cpp\n> @@ -38,6 +38,7 @@ namespace libcamera {\n> \n> LOG_DEFINE_CATEGORY(Request)\n> \n> +#ifndef __DOXYGEN_PUBLIC__\n> /**\n> * \\class Request::Private\n> * \\brief Request private data\n> @@ -306,6 +307,7 @@ void Request::Private::timeout()\n> \n> emitPrepareCompleted();\n> }\n> +#endif /* __DOXYGEN_PUBLIC__ */\n> \n> /**\n> * \\enum Request::Status\n> -- \n> Regards,\n> \n> Laurent Pinchart\n>","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 755B5BE173\n\tfor ;\n\tWed, 7 Aug 2024 05:16:43 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 6A02B6338D;\n\tWed, 7 Aug 2024 07:16:42 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 5E9466195A\n\tfor ;\n\tWed, 7 Aug 2024 07:16:41 +0200 (CEST)","from pendragon.ideasonboard.com\n\t(cpc89244-aztw30-2-0-cust6594.18-1.cable.virginm.net [86.31.185.195])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id B769A2EC;\n\tWed, 7 Aug 2024 07:15:48 +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=\"U0iNlw0z\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1723007748;\n\tbh=e4qe6KdpiqCYSX8jQyID5FpOp5+C4kmUeqdQatLIiX0=;\n\th=In-Reply-To:References:Subject:From:To:Date:From;\n\tb=U0iNlw0zPVMePzMfmKeq8flF7EDDtExIRbHT+gsIqOOC22IiF7F9Nd4K9j2g0gmbl\n\t16LEOILVCJlbo/NyCqAchrjtkEapQt+eYvZ9BVHD0u4U3BZjfw7BsdhYRwkvP/hz34\n\t61oOaWBvWTdDPuLxTSIx5GeIbObG/xUO6PWXqz/M=","Content-Type":"text/plain; charset=\"utf-8\"","MIME-Version":"1.0","Content-Transfer-Encoding":"quoted-printable","In-Reply-To":"<20240805143654.20870-6-laurent.pinchart@ideasonboard.com>","References":"<20240805143654.20870-1-laurent.pinchart@ideasonboard.com>\n\t<20240805143654.20870-6-laurent.pinchart@ideasonboard.com>","Subject":"Re: [PATCH v5 05/18] libcamera: Hide *::Private classes with\n\t__DOXYGEN_PUBLIC__","From":"Kieran Bingham ","To":"Laurent Pinchart ,\n\tlibcamera-devel@lists.libcamera.org","Date":"Wed, 07 Aug 2024 06:16:38 +0100","Message-ID":"<172300779879.1507574.13584029383654536681@ping.linuxembedded.co.uk>","User-Agent":"alot/0.10","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\" "}},{"id":30644,"web_url":"https://patchwork.libcamera.org/comment/30644/","msgid":"","date":"2024-08-07T08:08:59","subject":"Re: [PATCH v5 05/18] libcamera: Hide *::Private classes with\n\t__DOXYGEN_PUBLIC__","submitter":{"id":156,"url":"https://patchwork.libcamera.org/api/people/156/","name":"Dan Scally","email":"dan.scally@ideasonboard.com"},"content":"Hi Laurent\n\nOn 05/08/2024 15:36, Laurent Pinchart wrote:\n> The *::Private classes are part of the internal API, as their name\n> implies. They are defined in internal headers, but implemented in the\n> same source file as their public counterparts. This will cause Doxygen\n> to complain about missing class definition when splitting the public and\n> internal API documents, as the internal headers won't be parsed by\n> Doxygen for the public API documentation.\n>\n> Marking the classes with \\internal isn't enough. The directive prevents\n> the documentation block from being included in the output, but this\n> occurs at the generation stage, after the documentation blocks are\n> parsed. Fix this by completely hidding the implementation of the\n> *::Private classes from Doxygen using preprocessor conditional\n> compilation. To do so, introduce a new macro, __DOXYGEN_PUBLIC__, that\n> will be defined for the public API documentation only.\n>\n> Signed-off-by: Laurent Pinchart \n\n\nThis is fine too - I think I included them because I couldn't figure out a doxygen-only way of \nexcluding them...but this way works.\n\n\nReviewed-by: Daniel Scally \n\n> ---\n> src/libcamera/camera.cpp | 2 ++\n> src/libcamera/camera_manager.cpp | 2 ++\n> src/libcamera/framebuffer.cpp | 2 ++\n> src/libcamera/request.cpp | 2 ++\n> 4 files changed, 8 insertions(+)\n>\n> diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp\n> index 3c8f30d54401..aca466c9ba72 100644\n> --- a/src/libcamera/camera.cpp\n> +++ b/src/libcamera/camera.cpp\n> @@ -565,6 +565,7 @@ CameraConfiguration::Status CameraConfiguration::validateColorSpaces(ColorSpaceF\n> * \\brief The vector of stream configurations\n> */\n> \n> +#ifndef __DOXYGEN_PUBLIC__\n> /**\n> * \\class Camera::Private\n> * \\brief Base class for camera private data\n> @@ -725,6 +726,7 @@ void Camera::Private::setState(State state)\n> {\n> \tstate_.store(state, std::memory_order_release);\n> }\n> +#endif /* __DOXYGEN_PUBLIC__ */\n> \n> /**\n> * \\class Camera\n> diff --git a/src/libcamera/camera_manager.cpp b/src/libcamera/camera_manager.cpp\n> index 5a21132a08c2..fa44e33a135d 100644\n> --- a/src/libcamera/camera_manager.cpp\n> +++ b/src/libcamera/camera_manager.cpp\n> @@ -35,6 +35,7 @@ namespace libcamera {\n> \n> LOG_DEFINE_CATEGORY(Camera)\n> \n> +#ifndef __DOXYGEN_PUBLIC__\n> CameraManager::Private::Private()\n> \t: initialized_(false)\n> {\n> @@ -249,6 +250,7 @@ void CameraManager::Private::removeCamera(std::shared_ptr camera)\n> \tCameraManager *const o = LIBCAMERA_O_PTR();\n> \to->cameraRemoved.emit(camera);\n> }\n> +#endif /* __DOXYGEN_PUBLIC__ */\n> \n> /**\n> * \\class CameraManager\n> diff --git a/src/libcamera/framebuffer.cpp b/src/libcamera/framebuffer.cpp\n> index f39db1223432..826848f75a56 100644\n> --- a/src/libcamera/framebuffer.cpp\n> +++ b/src/libcamera/framebuffer.cpp\n> @@ -107,6 +107,7 @@ LOG_DEFINE_CATEGORY(Buffer)\n> * \\return The array of per-plane metadata\n> */\n> \n> +#ifndef __DOXYGEN_PUBLIC__\n> /**\n> * \\class FrameBuffer::Private\n> * \\brief Base class for FrameBuffer private data\n> @@ -209,6 +210,7 @@ FrameBuffer::Private::~Private()\n> * \\brief Retrieve the dynamic metadata\n> * \\return Dynamic metadata for the frame contained in the buffer\n> */\n> +#endif /* __DOXYGEN_PUBLIC__ */\n> \n> /**\n> * \\class FrameBuffer\n> diff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp\n> index 24fa3a57312e..8c56ed30d0c4 100644\n> --- a/src/libcamera/request.cpp\n> +++ b/src/libcamera/request.cpp\n> @@ -38,6 +38,7 @@ namespace libcamera {\n> \n> LOG_DEFINE_CATEGORY(Request)\n> \n> +#ifndef __DOXYGEN_PUBLIC__\n> /**\n> * \\class Request::Private\n> * \\brief Request private data\n> @@ -306,6 +307,7 @@ void Request::Private::timeout()\n> \n> \temitPrepareCompleted();\n> }\n> +#endif /* __DOXYGEN_PUBLIC__ */\n> \n> /**\n> * \\enum Request::Status","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 381C1C323E\n\tfor ;\n\tWed, 7 Aug 2024 08:09:05 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id C648163393;\n\tWed, 7 Aug 2024 10:09:03 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 7372F61946\n\tfor ;\n\tWed, 7 Aug 2024 10:09:02 +0200 (CEST)","from [192.168.0.43]\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 AAA096AF\n\tfor ;\n\tWed, 7 Aug 2024 10:08:09 +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=\"YCkbUfZH\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1723018089;\n\tbh=+lsaOU1bsWA6zKqb6VWGnvp4f69pCf/MA8hWp+IcNjc=;\n\th=Date:Subject:To:References:From:In-Reply-To:From;\n\tb=YCkbUfZHF898hMEE7YRE0ldrLu6j83VrJaXuro97L1sc35NPfMDwr7Q3lBfbMnOw9\n\tyGPPFsb779CFHX6kbqu4VG+ga1egJotVGtoerkLKWCFWSfkiw9cIWIL845ILvNkEw7\n\t0PDXj2nHiWjWno5ktTMxpc9hhQXWaU31sC2D6nOc=","Message-ID":"","Date":"Wed, 7 Aug 2024 09:08:59 +0100","MIME-Version":"1.0","User-Agent":"Mozilla Thunderbird","Subject":"Re: [PATCH v5 05/18] libcamera: Hide *::Private classes with\n\t__DOXYGEN_PUBLIC__","To":"libcamera-devel@lists.libcamera.org","References":"<20240805143654.20870-1-laurent.pinchart@ideasonboard.com>\n\t<20240805143654.20870-6-laurent.pinchart@ideasonboard.com>","Content-Language":"en-US","From":"Dan Scally ","Autocrypt":"addr=dan.scally@ideasonboard.com; keydata=\n\t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","In-Reply-To":"<20240805143654.20870-6-laurent.pinchart@ideasonboard.com>","Content-Type":"text/plain; charset=UTF-8; format=flowed","Content-Transfer-Encoding":"7bit","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\" "}},{"id":30675,"web_url":"https://patchwork.libcamera.org/comment/30675/","msgid":"<20240807130408.GD15173@pendragon.ideasonboard.com>","date":"2024-08-07T13:04:08","subject":"Re: [PATCH v5 05/18] libcamera: Hide *::Private classes with\n\t__DOXYGEN_PUBLIC__","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"content":"On Wed, Aug 07, 2024 at 06:16:38AM +0100, Kieran Bingham wrote:\n> Quoting Laurent Pinchart (2024-08-05 15:36:41)\n> > The *::Private classes are part of the internal API, as their name\n> > implies. They are defined in internal headers, but implemented in the\n> > same source file as their public counterparts. This will cause Doxygen\n> > to complain about missing class definition when splitting the public and\n> > internal API documents, as the internal headers won't be parsed by\n> > Doxygen for the public API documentation.\n> > \n> > Marking the classes with \\internal isn't enough. The directive prevents\n> > the documentation block from being included in the output, but this\n> \n> Does \\private or \\privatesection do anything here? or does that still\n> lead to the same issue as it will just mark them as 'private' and still\n> expect to find the definitions?\n\n\\private is for private members in the C++ sense. I don't see how it\ncould be used here.\n\n> > occurs at the generation stage, after the documentation blocks are\n> > parsed. Fix this by completely hidding the implementation of the\n> > *::Private classes from Doxygen using preprocessor conditional\n> > compilation. To do so, introduce a new macro, __DOXYGEN_PUBLIC__, that\n> > will be defined for the public API documentation only.\n> \n> It's a shame to be adding ifdefery. But understandable if this is the\n> best way forwards.\n\nI don't like it much either, but it's the best option I could find. We\nhave few public classes with Private data, so I think I can live with\nthis. Going forward, once we'll have a C API, Private will disappear\nanyway.\n\n> Reviewed-by: Kieran Bingham \n>\n> > Signed-off-by: Laurent Pinchart \n> > ---\n> > src/libcamera/camera.cpp | 2 ++\n> > src/libcamera/camera_manager.cpp | 2 ++\n> > src/libcamera/framebuffer.cpp | 2 ++\n> > src/libcamera/request.cpp | 2 ++\n> > 4 files changed, 8 insertions(+)\n> > \n> > diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp\n> > index 3c8f30d54401..aca466c9ba72 100644\n> > --- a/src/libcamera/camera.cpp\n> > +++ b/src/libcamera/camera.cpp\n> > @@ -565,6 +565,7 @@ CameraConfiguration::Status CameraConfiguration::validateColorSpaces(ColorSpaceF\n> > * \\brief The vector of stream configurations\n> > */\n> > \n> > +#ifndef __DOXYGEN_PUBLIC__\n> > /**\n> > * \\class Camera::Private\n> > * \\brief Base class for camera private data\n> > @@ -725,6 +726,7 @@ void Camera::Private::setState(State state)\n> > {\n> > state_.store(state, std::memory_order_release);\n> > }\n> > +#endif /* __DOXYGEN_PUBLIC__ */\n> > \n> > /**\n> > * \\class Camera\n> > diff --git a/src/libcamera/camera_manager.cpp b/src/libcamera/camera_manager.cpp\n> > index 5a21132a08c2..fa44e33a135d 100644\n> > --- a/src/libcamera/camera_manager.cpp\n> > +++ b/src/libcamera/camera_manager.cpp\n> > @@ -35,6 +35,7 @@ namespace libcamera {\n> > \n> > LOG_DEFINE_CATEGORY(Camera)\n> > \n> > +#ifndef __DOXYGEN_PUBLIC__\n> > CameraManager::Private::Private()\n> > : initialized_(false)\n> > {\n> > @@ -249,6 +250,7 @@ void CameraManager::Private::removeCamera(std::shared_ptr camera)\n> > CameraManager *const o = LIBCAMERA_O_PTR();\n> > o->cameraRemoved.emit(camera);\n> > }\n> > +#endif /* __DOXYGEN_PUBLIC__ */\n> > \n> > /**\n> > * \\class CameraManager\n> > diff --git a/src/libcamera/framebuffer.cpp b/src/libcamera/framebuffer.cpp\n> > index f39db1223432..826848f75a56 100644\n> > --- a/src/libcamera/framebuffer.cpp\n> > +++ b/src/libcamera/framebuffer.cpp\n> > @@ -107,6 +107,7 @@ LOG_DEFINE_CATEGORY(Buffer)\n> > * \\return The array of per-plane metadata\n> > */\n> > \n> > +#ifndef __DOXYGEN_PUBLIC__\n> > /**\n> > * \\class FrameBuffer::Private\n> > * \\brief Base class for FrameBuffer private data\n> > @@ -209,6 +210,7 @@ FrameBuffer::Private::~Private()\n> > * \\brief Retrieve the dynamic metadata\n> > * \\return Dynamic metadata for the frame contained in the buffer\n> > */\n> > +#endif /* __DOXYGEN_PUBLIC__ */\n> > \n> > /**\n> > * \\class FrameBuffer\n> > diff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp\n> > index 24fa3a57312e..8c56ed30d0c4 100644\n> > --- a/src/libcamera/request.cpp\n> > +++ b/src/libcamera/request.cpp\n> > @@ -38,6 +38,7 @@ namespace libcamera {\n> > \n> > LOG_DEFINE_CATEGORY(Request)\n> > \n> > +#ifndef __DOXYGEN_PUBLIC__\n> > /**\n> > * \\class Request::Private\n> > * \\brief Request private data\n> > @@ -306,6 +307,7 @@ void Request::Private::timeout()\n> > \n> > emitPrepareCompleted();\n> > }\n> > +#endif /* __DOXYGEN_PUBLIC__ */\n> > \n> > /**\n> > * \\enum Request::Status","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 6EE44BE173\n\tfor ;\n\tWed, 7 Aug 2024 13:04:33 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 9F1A2633B1;\n\tWed, 7 Aug 2024 15:04:32 +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 679D363382\n\tfor ;\n\tWed, 7 Aug 2024 15:04:31 +0200 (CEST)","from pendragon.ideasonboard.com (81-175-209-231.bb.dnainternet.fi\n\t[81.175.209.231])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 5BFFD6AF;\n\tWed, 7 Aug 2024 15:03:38 +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=\"PmxNceKD\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1723035818;\n\tbh=Q6pMSIQL9y7R+XeuPUi0d8+bJBYR8c9Aw7ousvY2H3M=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=PmxNceKD7uvqcJ3i46kPNRclHkzNRzpCvP9EQLVHPKf7OD0qzwzs8LD1bylEWfQ4t\n\tmVIQbDRyvGaFsVYFWiGGiESiPZ6GizMH0YznIGSD6gGo6FmsH4dHEbtPsWpByLvx5+\n\tNx+QG0jYsFdFAYQTZ73ddVFMo+7G0UknHQ3X1kw4=","Date":"Wed, 7 Aug 2024 16:04:08 +0300","From":"Laurent Pinchart ","To":"Kieran Bingham ","Cc":"libcamera-devel@lists.libcamera.org","Subject":"Re: [PATCH v5 05/18] libcamera: Hide *::Private classes with\n\t__DOXYGEN_PUBLIC__","Message-ID":"<20240807130408.GD15173@pendragon.ideasonboard.com>","References":"<20240805143654.20870-1-laurent.pinchart@ideasonboard.com>\n\t<20240805143654.20870-6-laurent.pinchart@ideasonboard.com>\n\t<172300779879.1507574.13584029383654536681@ping.linuxembedded.co.uk>","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","In-Reply-To":"<172300779879.1507574.13584029383654536681@ping.linuxembedded.co.uk>","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\" "}}]