[{"id":30628,"web_url":"https://patchwork.libcamera.org/comment/30628/","msgid":"","date":"2024-08-06T13:34:56","subject":"Re: [PATCH v5 02/18] libcamera: Make all internal headers visible to\n\tDoxygen","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> Two classes that have both public and internal headers, namely Camera\n> and Request, make only their public header visible to Doxygen through a\n> file directive. Fix them.\n>\n> Signed-off-by: Laurent Pinchart \n\n\nReviewed-by: Daniel Scally \n\n\nHow did you notice this, out of curiosity? I never saw any Doxygen messages about it.\n\n> ---\n> src/libcamera/camera.cpp | 5 +++++\n> src/libcamera/request.cpp | 5 +++++\n> 2 files changed, 10 insertions(+)\n>\n> diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp\n> index 67f3490133b2..f89510ea0472 100644\n> --- a/src/libcamera/camera.cpp\n> +++ b/src/libcamera/camera.cpp\n> @@ -117,6 +117,11 @@\n> * of view is affected by the pipeline.\n> */\n> \n> +/**\n> + * \\file libcamera/internal/camera.h\n> + * \\brief Internal camera device handling\n> + */\n> +\n> namespace libcamera {\n> \n> LOG_DECLARE_CATEGORY(Camera)\n> diff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp\n> index cfb451e908da..fdf12c1e9088 100644\n> --- a/src/libcamera/request.cpp\n> +++ b/src/libcamera/request.cpp\n> @@ -28,6 +28,11 @@\n> * \\brief Describes a frame capture request to be processed by a camera\n> */\n> \n> +/**\n> + * \\file libcamera/internal/request.h\n> + * \\brief Internal support for request handling\n> + */\n> +\n> namespace libcamera {\n> \n> LOG_DEFINE_CATEGORY(Request)","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 2DB8EC323E\n\tfor ;\n\tTue, 6 Aug 2024 13:35:02 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 2EE3663393;\n\tTue, 6 Aug 2024 15:35:01 +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 C95EF6195D\n\tfor ;\n\tTue, 6 Aug 2024 15:34:59 +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 A13774CD\n\tfor ;\n\tTue, 6 Aug 2024 15:34:07 +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=\"DpCcn5cx\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1722951247;\n\tbh=AtEf66c2SftH+bySeGGCHyY2OQTlrlJSkZu8nmSkWTE=;\n\th=Date:Subject:To:References:From:In-Reply-To:From;\n\tb=DpCcn5cxKfMtQx7Phen994HuRdbCAHEfzRckkE0O8fwka98WWZugaEXB5QrXTKjXv\n\tnIW+bqzEA1nDgBKh7BCWaHn7eJMRSJ+CT6ymuwh6exgzOrNr2cQBtyEGI7X8/BFe6e\n\tEULFlq5PqS9zxtnE6uLUW98bPk2m+JBQPho5ePS0=","Message-ID":"","Date":"Tue, 6 Aug 2024 14:34:56 +0100","MIME-Version":"1.0","User-Agent":"Mozilla Thunderbird","Subject":"Re: [PATCH v5 02/18] libcamera: Make all internal headers visible to\n\tDoxygen","To":"libcamera-devel@lists.libcamera.org","References":"<20240805143654.20870-1-laurent.pinchart@ideasonboard.com>\n\t<20240805143654.20870-3-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-3-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":30629,"web_url":"https://patchwork.libcamera.org/comment/30629/","msgid":"<20240806133938.GF32045@pendragon.ideasonboard.com>","date":"2024-08-06T13:39:38","subject":"Re: [PATCH v5 02/18] libcamera: Make all internal headers visible to\n\tDoxygen","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"content":"On Tue, Aug 06, 2024 at 02:34:56PM +0100, Daniel Scally wrote:\n> On 05/08/2024 15:36, Laurent Pinchart wrote:\n> > Two classes that have both public and internal headers, namely Camera\n> > and Request, make only their public header visible to Doxygen through a\n> > file directive. Fix them.\n> >\n> > Signed-off-by: Laurent Pinchart \n> \n> Reviewed-by: Daniel Scally \n> \n> How did you notice this, out of curiosity? I never saw any Doxygen messages about it.\n\nJust by chance, when looking at the four classes that have public and\ninternal headers of the same name, I realized there was a discrepancy.\n\n> > ---\n> > src/libcamera/camera.cpp | 5 +++++\n> > src/libcamera/request.cpp | 5 +++++\n> > 2 files changed, 10 insertions(+)\n> >\n> > diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp\n> > index 67f3490133b2..f89510ea0472 100644\n> > --- a/src/libcamera/camera.cpp\n> > +++ b/src/libcamera/camera.cpp\n> > @@ -117,6 +117,11 @@\n> > * of view is affected by the pipeline.\n> > */\n> > \n> > +/**\n> > + * \\file libcamera/internal/camera.h\n> > + * \\brief Internal camera device handling\n> > + */\n> > +\n> > namespace libcamera {\n> > \n> > LOG_DECLARE_CATEGORY(Camera)\n> > diff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp\n> > index cfb451e908da..fdf12c1e9088 100644\n> > --- a/src/libcamera/request.cpp\n> > +++ b/src/libcamera/request.cpp\n> > @@ -28,6 +28,11 @@\n> > * \\brief Describes a frame capture request to be processed by a camera\n> > */\n> > \n> > +/**\n> > + * \\file libcamera/internal/request.h\n> > + * \\brief Internal support for request handling\n> > + */\n> > +\n> > namespace libcamera {\n> > \n> > LOG_DEFINE_CATEGORY(Request)","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 E9687BE173\n\tfor ;\n\tTue, 6 Aug 2024 13:40:03 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 3B2BC63380;\n\tTue, 6 Aug 2024 15:40:03 +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 89DA46195D\n\tfor ;\n\tTue, 6 Aug 2024 15:40:01 +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 267E24CD;\n\tTue, 6 Aug 2024 15:39: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=\"oCHazDEn\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1722951549;\n\tbh=Ja4YbRSslWvx9UQd8UOgdqWz+zeMUZLZ5klCk+PV+lw=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=oCHazDEnI+fgf4hvpnbt4E5wil4tl3VfsEeduJ2CSVOlbJAzQmbGHF1NV6uHfrKL3\n\tM26uGfu8xMb0pm5YNZSkNhIYH1O1APzjfRHKFR/UYT64GrHQWdAFCCDKghJK448fDG\n\tRGf1ytQFt49Bmpe6VlPJ5VotmkLwbFzWyjeu29Vc=","Date":"Tue, 6 Aug 2024 16:39:38 +0300","From":"Laurent Pinchart ","To":"Dan Scally ","Cc":"libcamera-devel@lists.libcamera.org","Subject":"Re: [PATCH v5 02/18] libcamera: Make all internal headers visible to\n\tDoxygen","Message-ID":"<20240806133938.GF32045@pendragon.ideasonboard.com>","References":"<20240805143654.20870-1-laurent.pinchart@ideasonboard.com>\n\t<20240805143654.20870-3-laurent.pinchart@ideasonboard.com>\n\t","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","In-Reply-To":"","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":30639,"web_url":"https://patchwork.libcamera.org/comment/30639/","msgid":"<172300675626.1507574.7750167013694277381@ping.linuxembedded.co.uk>","date":"2024-08-07T04:59:16","subject":"Re: [PATCH v5 02/18] libcamera: Make all internal headers visible to\n\tDoxygen","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-06 14:39:38)\n> On Tue, Aug 06, 2024 at 02:34:56PM +0100, Daniel Scally wrote:\n> > On 05/08/2024 15:36, Laurent Pinchart wrote:\n> > > Two classes that have both public and internal headers, namely Camera\n> > > and Request, make only their public header visible to Doxygen through a\n> > > file directive. Fix them.\n> > >\n> > > Signed-off-by: Laurent Pinchart \n> > \n> > Reviewed-by: Daniel Scally \n> > \n> > How did you notice this, out of curiosity? I never saw any Doxygen messages about it.\n> \n> Just by chance, when looking at the four classes that have public and\n> internal headers of the same name, I realized there was a discrepancy.\n> \n> > > ---\n> > > src/libcamera/camera.cpp | 5 +++++\n> > > src/libcamera/request.cpp | 5 +++++\n> > > 2 files changed, 10 insertions(+)\n> > >\n> > > diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp\n> > > index 67f3490133b2..f89510ea0472 100644\n> > > --- a/src/libcamera/camera.cpp\n> > > +++ b/src/libcamera/camera.cpp\n> > > @@ -117,6 +117,11 @@\n> > > * of view is affected by the pipeline.\n> > > */\n> > > \n> > > +/**\n> > > + * \\file libcamera/internal/camera.h\n> > > + * \\brief Internal camera device handling\n> > > + */\n\nSo the file directives cause doxygen to incoud\n\nBased on https://www.doxygen.nl/manual/commands.html#cmdfile the file\ndirective only applies to the comment block it's in as I understand it.\nSo this is 'only' adding a brief to the internal headers? Or is it doing\nmore like actually pulling the file into the documentation?\n\nEither way, it seems consistent, and meets our coding style requirement\n\"Every documented header file shall have a \\file documentation block in\nthe .cpp source file.\"\n\nOut of curiousity - what happens if the path is not unique? Is there a\nsearch order? Is a file in the same location as the .cpp chosen first?\n\nA quick check highlights :\n\nkbingham@Monstersaurus:~/iob/libcamera/libcamera-clean$ gg \"\\\\\\\\file \" | sed 's/.*file //' | sort | uniq -c | grep \"2 \"\n 2 agc.h\n 2 awb.h\n 2 blc.h\n 2 delayed_controls.h\n 2 ipa_context.h\n\nDoes any action need to be taken on those files? \n\n\nHang on - I'm on 2/18 - I should probably check the rest of the series\nbefore sending myself on rabbit holes ... ;-)\n\nAnyway, for this patch \n\nReviewed-by: Kieran Bingham \n\n> > > +\n> > > namespace libcamera {\n> > > \n> > > LOG_DECLARE_CATEGORY(Camera)\n> > > diff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp\n> > > index cfb451e908da..fdf12c1e9088 100644\n> > > --- a/src/libcamera/request.cpp\n> > > +++ b/src/libcamera/request.cpp\n> > > @@ -28,6 +28,11 @@\n> > > * \\brief Describes a frame capture request to be processed by a camera\n> > > */\n> > > \n> > > +/**\n> > > + * \\file libcamera/internal/request.h\n> > > + * \\brief Internal support for request handling\n> > > + */\n> > > +\n> > > namespace libcamera {\n> > > \n> > > LOG_DEFINE_CATEGORY(Request)\n> \n> -- \n> Regards,\n> \n> Laurent Pinchart","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 84B10C323E\n\tfor ;\n\tWed, 7 Aug 2024 04:59:21 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id AC8056195A;\n\tWed, 7 Aug 2024 06:59:20 +0200 (CEST)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 119836195A\n\tfor ;\n\tWed, 7 Aug 2024 06:59:19 +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 568706AF;\n\tWed, 7 Aug 2024 06:58:26 +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=\"VpIY8UHq\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1723006706;\n\tbh=PcYGp7DGmAoAnWeg8qg3v4p9uQuFILLSu0rqunzzYUA=;\n\th=In-Reply-To:References:Subject:From:Cc:To:Date:From;\n\tb=VpIY8UHqK+rOuMQc8/gwWFLhCiQESy4GD9Bkvw3RNYxgcsuyOfj0itXdzF2PL5Js3\n\tSOyiVYlNVOIhqWd+ozEUzfmD62K4uj2Fz/B41shgxDtZtOteG5Fr8jH29kIrKlVjdf\n\t9zoQF5cD5HVAXKsW4A5xA7uTslrvfMQSh9d7+5Wo=","Content-Type":"text/plain; charset=\"utf-8\"","MIME-Version":"1.0","Content-Transfer-Encoding":"quoted-printable","In-Reply-To":"<20240806133938.GF32045@pendragon.ideasonboard.com>","References":"<20240805143654.20870-1-laurent.pinchart@ideasonboard.com>\n\t<20240805143654.20870-3-laurent.pinchart@ideasonboard.com>\n\t\n\t<20240806133938.GF32045@pendragon.ideasonboard.com>","Subject":"Re: [PATCH v5 02/18] libcamera: Make all internal headers visible to\n\tDoxygen","From":"Kieran Bingham ","Cc":"libcamera-devel@lists.libcamera.org","To":"Dan Scally ,\n\tLaurent Pinchart ","Date":"Wed, 07 Aug 2024 05:59:16 +0100","Message-ID":"<172300675626.1507574.7750167013694277381@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":30672,"web_url":"https://patchwork.libcamera.org/comment/30672/","msgid":"<20240807125033.GA15173@pendragon.ideasonboard.com>","date":"2024-08-07T12:50:33","subject":"Re: [PATCH v5 02/18] libcamera: Make all internal headers visible to\n\tDoxygen","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 05:59:16AM +0100, Kieran Bingham wrote:\n> Quoting Laurent Pinchart (2024-08-06 14:39:38)\n> > On Tue, Aug 06, 2024 at 02:34:56PM +0100, Daniel Scally wrote:\n> > > On 05/08/2024 15:36, Laurent Pinchart wrote:\n> > > > Two classes that have both public and internal headers, namely Camera\n> > > > and Request, make only their public header visible to Doxygen through a\n> > > > file directive. Fix them.\n> > > >\n> > > > Signed-off-by: Laurent Pinchart \n> > > \n> > > Reviewed-by: Daniel Scally \n> > > \n> > > How did you notice this, out of curiosity? I never saw any Doxygen messages about it.\n> > \n> > Just by chance, when looking at the four classes that have public and\n> > internal headers of the same name, I realized there was a discrepancy.\n> > \n> > > > ---\n> > > > src/libcamera/camera.cpp | 5 +++++\n> > > > src/libcamera/request.cpp | 5 +++++\n> > > > 2 files changed, 10 insertions(+)\n> > > >\n> > > > diff --git a/src/libcamera/camera.cpp b/src/libcamera/camera.cpp\n> > > > index 67f3490133b2..f89510ea0472 100644\n> > > > --- a/src/libcamera/camera.cpp\n> > > > +++ b/src/libcamera/camera.cpp\n> > > > @@ -117,6 +117,11 @@\n> > > > * of view is affected by the pipeline.\n> > > > */\n> > > > \n> > > > +/**\n> > > > + * \\file libcamera/internal/camera.h\n> > > > + * \\brief Internal camera device handling\n> > > > + */\n> \n> So the file directives cause doxygen to incoud\n> \n> Based on https://www.doxygen.nl/manual/commands.html#cmdfile the file\n> directive only applies to the comment block it's in as I understand it.\n> So this is 'only' adding a brief to the internal headers? Or is it doing\n> more like actually pulling the file into the documentation?\n\nI don't remember exactly why the file directive is needed, I just recall\nit is for some reason that matters :-)\n\n> Either way, it seems consistent, and meets our coding style requirement\n> \"Every documented header file shall have a \\file documentation block in\n> the .cpp source file.\"\n>\n> Out of curiousity - what happens if the path is not unique? Is there a\n> search order? Is a file in the same location as the .cpp chosen first?\n\nDoxygen complains in that case.\n\n> A quick check highlights :\n> \n> kbingham@Monstersaurus:~/iob/libcamera/libcamera-clean$ gg \"\\\\\\\\file \" | sed 's/.*file //' | sort | uniq -c | grep \"2 \"\n> 2 agc.h\n> 2 awb.h\n> 2 blc.h\n> 2 delayed_controls.h\n> 2 ipa_context.h\n> \n> Does any action need to be taken on those files? \n\nAt least one of each isn't part of the documentation build, so we should\nbe fine for now.\n\n> Hang on - I'm on 2/18 - I should probably check the rest of the series\n> before sending myself on rabbit holes ... ;-)\n> \n> Anyway, for this patch \n> \n> Reviewed-by: Kieran Bingham \n> \n> > > > +\n> > > > namespace libcamera {\n> > > > \n> > > > LOG_DECLARE_CATEGORY(Camera)\n> > > > diff --git a/src/libcamera/request.cpp b/src/libcamera/request.cpp\n> > > > index cfb451e908da..fdf12c1e9088 100644\n> > > > --- a/src/libcamera/request.cpp\n> > > > +++ b/src/libcamera/request.cpp\n> > > > @@ -28,6 +28,11 @@\n> > > > * \\brief Describes a frame capture request to be processed by a camera\n> > > > */\n> > > > \n> > > > +/**\n> > > > + * \\file libcamera/internal/request.h\n> > > > + * \\brief Internal support for request handling\n> > > > + */\n> > > > +\n> > > > namespace libcamera {\n> > > > \n> > > > LOG_DEFINE_CATEGORY(Request)","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 175C3BE173\n\tfor ;\n\tWed, 7 Aug 2024 12:51:00 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id BB09963394;\n\tWed, 7 Aug 2024 14:50:58 +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 3E5746337F\n\tfor ;\n\tWed, 7 Aug 2024 14:50:57 +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 2974B2EC;\n\tWed, 7 Aug 2024 14:50:04 +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=\"PYNppnMt\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1723035004;\n\tbh=Jaj/KXrWX9xd2flakvZ2Wt85KJ8DddYwLRI9iV+5/68=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=PYNppnMtBDa+s/LjzWtAcVfjdc87Pdqzx0WEqZ203Q4pJABf1V/eqYJpZ1R8Q+e7G\n\ty0fmvH1JOR7bBBpZRhHC881rgSZRhfKORAwjhLJiIwgSbZi0+SSOwK7P0VYO+RyU4z\n\tyZ8OSYMn1lY55JbYn16+/xCd0qnm1hp0jzolaK4U=","Date":"Wed, 7 Aug 2024 15:50:33 +0300","From":"Laurent Pinchart ","To":"Kieran Bingham ","Cc":"Dan Scally ,\n\tlibcamera-devel@lists.libcamera.org","Subject":"Re: [PATCH v5 02/18] libcamera: Make all internal headers visible to\n\tDoxygen","Message-ID":"<20240807125033.GA15173@pendragon.ideasonboard.com>","References":"<20240805143654.20870-1-laurent.pinchart@ideasonboard.com>\n\t<20240805143654.20870-3-laurent.pinchart@ideasonboard.com>\n\t\n\t<20240806133938.GF32045@pendragon.ideasonboard.com>\n\t<172300675626.1507574.7750167013694277381@ping.linuxembedded.co.uk>","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","In-Reply-To":"<172300675626.1507574.7750167013694277381@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\" "}}]