[{"id":18297,"web_url":"https://patchwork.libcamera.org/comment/18297/","msgid":"","date":"2021-07-24T06:48:29","subject":"Re: [libcamera-devel] [RFC PATCH 01/17] libcamera: base: class:\n\tDocument Extensible::_d() functions","submitter":{"id":5,"url":"https://patchwork.libcamera.org/api/people/5/","name":"Niklas Söderlund","email":"niklas.soderlund@ragnatech.se"},"content":"Hi Laurent,\n\nThanks for your work.\n\nOn 2021-07-23 07:00:20 +0300, Laurent Pinchart wrote:\n> The Extensible::_d() functions are meant to be called by users of the\n> class. Document them.\n> \n> Signed-off-by: Laurent Pinchart \n\nReviewed-by: Niklas Söderlund \n\n> ---\n> include/libcamera/base/class.h | 2 --\n> src/libcamera/base/class.cpp | 17 +++++++++++++++++\n> 2 files changed, 17 insertions(+), 2 deletions(-)\n> \n> diff --git a/include/libcamera/base/class.h b/include/libcamera/base/class.h\n> index c2e1d3534ed1..9c7f0f2e6e27 100644\n> --- a/include/libcamera/base/class.h\n> +++ b/include/libcamera/base/class.h\n> @@ -88,7 +88,6 @@ public:\n> \tExtensible(Private *d);\n> \n> protected:\n> -#ifndef __DOXYGEN__\n> \ttemplate\n> \tconst T *_d() const\n> \t{\n> @@ -100,7 +99,6 @@ protected:\n> \t{\n> \t\treturn static_cast(d_.get());\n> \t}\n> -#endif\n> \n> private:\n> \tconst std::unique_ptr d_;\n> diff --git a/src/libcamera/base/class.cpp b/src/libcamera/base/class.cpp\n> index 26b4967726d6..d0899671ca11 100644\n> --- a/src/libcamera/base/class.cpp\n> +++ b/src/libcamera/base/class.cpp\n> @@ -150,6 +150,23 @@ Extensible::Extensible(Extensible::Private *d)\n> {\n> }\n> \n> +/**\n> + * \\fn Extensible::_d() const\n> + * \\brief Retrieve the private data instance\n> + *\n> + * This template function isn't meant to be called directly. Instead, classes\n> + * derived from Extensible get, through the LIBCAMERA_DECLARE_PRIVATE() macro,\n> + * overriden _d() functions that return the correct pointer type to the\n> + * corresponding derived Private class.\n> + *\n> + * \\return A pointer to the private data instance\n> + */\n> +\n> +/**\n> + * \\fn Extensible::_d()\n> + * \\copydoc Extensible::_d() const\n> + */\n> +\n> /**\n> * \\var Extensible::d_\n> * \\brief Pointer to the private data instance\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 DA0A3C322C\n\tfor ;\n\tSat, 24 Jul 2021 06:48:33 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 28FA4687A9;\n\tSat, 24 Jul 2021 08:48:33 +0200 (CEST)","from mail-lf1-x131.google.com (mail-lf1-x131.google.com\n\t[IPv6:2a00:1450:4864:20::131])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 66FE260273\n\tfor ;\n\tSat, 24 Jul 2021 08:48:31 +0200 (CEST)","by mail-lf1-x131.google.com with SMTP id f18so5728754lfu.10\n\tfor ;\n\tFri, 23 Jul 2021 23:48:31 -0700 (PDT)","from localhost (h-46-59-88-219.A463.priv.bahnhof.se.\n\t[46.59.88.219]) by smtp.gmail.com with ESMTPSA id\n\t14sm2652253lfq.130.2021.07.23.23.48.29\n\t(version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256);\n\tFri, 23 Jul 2021 23:48:29 -0700 (PDT)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (2048-bit key;\n\tunprotected) header.d=ragnatech-se.20150623.gappssmtp.com\n\theader.i=@ragnatech-se.20150623.gappssmtp.com\n\theader.b=\"d6aI+Yya\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=ragnatech-se.20150623.gappssmtp.com; s=20150623;\n\th=date:from:to:cc:subject:message-id:references:mime-version\n\t:content-disposition:content-transfer-encoding:in-reply-to;\n\tbh=/Ty99zVKZJ79MQGuxiukseoSo6oDIFfP9d1QyTMZn0I=;\n\tb=d6aI+YyaZ5gYaSpunAnpUUk3S7mmaSZRpVQDmRlW/EgJ27nqakH+9wxDP5mpPAjtYo\n\tYncaIf4rsSi/bi3KhVXdCyrDpqX9MnuBf0ZoBaSni3LZoHfBsr/DnJMM+/h6R965UV/J\n\tlweCoZkwlcimddGo4/iaRNhsEDHYanKguQpo9oZYSJQ6DR6+FMZ3L+RXZthQO3nitg/r\n\tTAND7foW8ZZNw83xdrXXckksZlG0Qy9hMJWKhCbD0vqPlP9Ia6aj6Fx8TbT64H+BCIzk\n\t7Cb+PdYCkUn4s9vknIqwv65cxCTw8v5cDsidUwC5nKkfW4tlBmmHpOBhVR0vHLJ3N1Tw\n\tiFOg==","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20161025;\n\th=x-gm-message-state:date:from:to:cc:subject:message-id:references\n\t:mime-version:content-disposition:content-transfer-encoding\n\t:in-reply-to;\n\tbh=/Ty99zVKZJ79MQGuxiukseoSo6oDIFfP9d1QyTMZn0I=;\n\tb=j1iRvfbXqtSMBMfLtqPCWf+0L9PHGXRCYeM7jyscmHnPdxxMfe0iwRQkTz6INzk1+l\n\t/uz4ZbT2mauIlrW8wXBOjn8w4cHwXi5ZQfLb89gNflooKzHHiZK6bW5rBiVlejZ7XC4t\n\tsNscB11TdAUfzGpKORp25a51CHBz6JCo6hbyQgfkKd16ZAvBnefQPGfYVP5IauKjOudv\n\tt8UUQBrc2e7AQCFAfaXEglAtcL4+ege6wN1njBBA6xXjGQO7L8asuwUgHyBBX7S/476G\n\t/++u3nOv+Qip/ET5ClFRa90FOgsQ5j6iOHITbWU81LZJEcdyp8xqk8UWjtKuCtBqe8hD\n\toshQ==","X-Gm-Message-State":"AOAM533CF8sL8xmLWbRRxDtA3mGvcJWyZbwudAwd4/h5V94rbx5sVmQp\n\tqgpOAi92XINcOq1O7fBqhRBU8l5UGcgOBA==","X-Google-Smtp-Source":"ABdhPJwOBV8gGNdXfVMlUjw3NA8JYVsUDaQrOIEbnv+nzaV2rr4a/gWHwCQf/MMvM3RmdL0FWDrBww==","X-Received":"by 2002:a19:ee19:: with SMTP id\n\tg25mr5614612lfb.140.1627109310731; \n\tFri, 23 Jul 2021 23:48:30 -0700 (PDT)","Date":"Sat, 24 Jul 2021 08:48:29 +0200","From":"Niklas =?iso-8859-1?q?S=F6derlund?= ","To":"Laurent Pinchart ","Message-ID":"","References":"<20210723040036.32346-1-laurent.pinchart@ideasonboard.com>\n\t<20210723040036.32346-2-laurent.pinchart@ideasonboard.com>","MIME-Version":"1.0","Content-Type":"text/plain; charset=iso-8859-1","Content-Disposition":"inline","Content-Transfer-Encoding":"8bit","In-Reply-To":"<20210723040036.32346-2-laurent.pinchart@ideasonboard.com>","Subject":"Re: [libcamera-devel] [RFC PATCH 01/17] libcamera: base: class:\n\tDocument Extensible::_d() functions","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","Cc":"libcamera-devel@lists.libcamera.org","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}},{"id":18422,"web_url":"https://patchwork.libcamera.org/comment/18422/","msgid":"<20210729200542.6yizqyuzfdpnqvsz@uno.localdomain>","date":"2021-07-29T20:05:42","subject":"Re: [libcamera-devel] [RFC PATCH 01/17] libcamera: base: class:\n\tDocument Extensible::_d() functions","submitter":{"id":3,"url":"https://patchwork.libcamera.org/api/people/3/","name":"Jacopo Mondi","email":"jacopo@jmondi.org"},"content":"Hi Laurent,\n\nOn Fri, Jul 23, 2021 at 07:00:20AM +0300, Laurent Pinchart wrote:\n> The Extensible::_d() functions are meant to be called by users of the\n> class. Document them.\n>\n> Signed-off-by: Laurent Pinchart \n> ---\n> include/libcamera/base/class.h | 2 --\n> src/libcamera/base/class.cpp | 17 +++++++++++++++++\n> 2 files changed, 17 insertions(+), 2 deletions(-)\n>\n> diff --git a/include/libcamera/base/class.h b/include/libcamera/base/class.h\n> index c2e1d3534ed1..9c7f0f2e6e27 100644\n> --- a/include/libcamera/base/class.h\n> +++ b/include/libcamera/base/class.h\n> @@ -88,7 +88,6 @@ public:\n> \tExtensible(Private *d);\n>\n> protected:\n> -#ifndef __DOXYGEN__\n> \ttemplate\n> \tconst T *_d() const\n> \t{\n> @@ -100,7 +99,6 @@ protected:\n> \t{\n> \t\treturn static_cast(d_.get());\n> \t}\n> -#endif\n>\n> private:\n> \tconst std::unique_ptr d_;\n> diff --git a/src/libcamera/base/class.cpp b/src/libcamera/base/class.cpp\n> index 26b4967726d6..d0899671ca11 100644\n> --- a/src/libcamera/base/class.cpp\n> +++ b/src/libcamera/base/class.cpp\n> @@ -150,6 +150,23 @@ Extensible::Extensible(Extensible::Private *d)\n> {\n> }\n>\n> +/**\n> + * \\fn Extensible::_d() const\n> + * \\brief Retrieve the private data instance\n> + *\n> + * This template function isn't meant to be called directly. Instead, classes\n> + * derived from Extensible get, through the LIBCAMERA_DECLARE_PRIVATE() macro,\n> + * overriden _d() functions that return the correct pointer type to the\n> + * corresponding derived Private class.\n\nIt really took me a while to understand that we have Extensible::_d()\nand the overriden versions, and it's written just here :)\n\nProbably because the commit message says \"are meant to be called by\nusers\" and this starts with \"isn't meant to be called directly\" :)\n\nReviewed-by: Jacopo Mondi \n\nThanks\n j\n\n> + *\n> + * \\return A pointer to the private data instance\n> + */\n> +\n> +/**\n> + * \\fn Extensible::_d()\n> + * \\copydoc Extensible::_d() const\n> + */\n> +\n> /**\n> * \\var Extensible::d_\n> * \\brief Pointer to the private data instance\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 3BC57C3230\n\tfor ;\n\tThu, 29 Jul 2021 20:04:58 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 99D3F687BF;\n\tThu, 29 Jul 2021 22:04:57 +0200 (CEST)","from relay8-d.mail.gandi.net (relay8-d.mail.gandi.net\n\t[217.70.183.201])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 978E1687BA\n\tfor ;\n\tThu, 29 Jul 2021 22:04:56 +0200 (CEST)","(Authenticated sender: jacopo@jmondi.org)\n\tby relay8-d.mail.gandi.net (Postfix) with ESMTPSA id C5BB11BF203;\n\tThu, 29 Jul 2021 20:04:55 +0000 (UTC)"],"Date":"Thu, 29 Jul 2021 22:05:42 +0200","From":"Jacopo Mondi ","To":"Laurent Pinchart ","Message-ID":"<20210729200542.6yizqyuzfdpnqvsz@uno.localdomain>","References":"<20210723040036.32346-1-laurent.pinchart@ideasonboard.com>\n\t<20210723040036.32346-2-laurent.pinchart@ideasonboard.com>","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","In-Reply-To":"<20210723040036.32346-2-laurent.pinchart@ideasonboard.com>","Subject":"Re: [libcamera-devel] [RFC PATCH 01/17] libcamera: base: class:\n\tDocument Extensible::_d() functions","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","Cc":"libcamera-devel@lists.libcamera.org","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}},{"id":18432,"web_url":"https://patchwork.libcamera.org/comment/18432/","msgid":"","date":"2021-07-30T02:28:39","subject":"Re: [libcamera-devel] [RFC PATCH 01/17] libcamera: base: class:\n\tDocument Extensible::_d() functions","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"content":"Hi Jacopo,\n\nOn Thu, Jul 29, 2021 at 10:05:42PM +0200, Jacopo Mondi wrote:\n> On Fri, Jul 23, 2021 at 07:00:20AM +0300, Laurent Pinchart wrote:\n> > The Extensible::_d() functions are meant to be called by users of the\n> > class. Document them.\n> >\n> > Signed-off-by: Laurent Pinchart \n> > ---\n> > include/libcamera/base/class.h | 2 --\n> > src/libcamera/base/class.cpp | 17 +++++++++++++++++\n> > 2 files changed, 17 insertions(+), 2 deletions(-)\n> >\n> > diff --git a/include/libcamera/base/class.h b/include/libcamera/base/class.h\n> > index c2e1d3534ed1..9c7f0f2e6e27 100644\n> > --- a/include/libcamera/base/class.h\n> > +++ b/include/libcamera/base/class.h\n> > @@ -88,7 +88,6 @@ public:\n> > \tExtensible(Private *d);\n> >\n> > protected:\n> > -#ifndef __DOXYGEN__\n> > \ttemplate\n> > \tconst T *_d() const\n> > \t{\n> > @@ -100,7 +99,6 @@ protected:\n> > \t{\n> > \t\treturn static_cast(d_.get());\n> > \t}\n> > -#endif\n> >\n> > private:\n> > \tconst std::unique_ptr d_;\n> > diff --git a/src/libcamera/base/class.cpp b/src/libcamera/base/class.cpp\n> > index 26b4967726d6..d0899671ca11 100644\n> > --- a/src/libcamera/base/class.cpp\n> > +++ b/src/libcamera/base/class.cpp\n> > @@ -150,6 +150,23 @@ Extensible::Extensible(Extensible::Private *d)\n> > {\n> > }\n> >\n> > +/**\n> > + * \\fn Extensible::_d() const\n> > + * \\brief Retrieve the private data instance\n> > + *\n> > + * This template function isn't meant to be called directly. Instead, classes\n> > + * derived from Extensible get, through the LIBCAMERA_DECLARE_PRIVATE() macro,\n> > + * overriden _d() functions that return the correct pointer type to the\n> > + * corresponding derived Private class.\n> \n> It really took me a while to understand that we have Extensible::_d()\n> and the overriden versions, and it's written just here :)\n> \n> Probably because the commit message says \"are meant to be called by\n> users\" and this starts with \"isn't meant to be called directly\" :)\n\nThe issue is that the Extensible::_d() function isn't meant to be called\ndirectly, but I haven't found a way to get doxygen to document the\noverridden functions generated by LIBCAMERA_DECLARE_PRIVATE(). I've thus\ndecided to document this in the base Extensible::_d() function as the\nbest workaround I could find :-S.\n\n> Reviewed-by: Jacopo Mondi \n> \n> > + *\n> > + * \\return A pointer to the private data instance\n> > + */\n> > +\n> > +/**\n> > + * \\fn Extensible::_d()\n> > + * \\copydoc Extensible::_d() const\n> > + */\n> > +\n> > /**\n> > * \\var Extensible::d_\n> > * \\brief Pointer to the private data instance","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 D2F49C322E\n\tfor ;\n\tFri, 30 Jul 2021 02:28:49 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 1E555687BF;\n\tFri, 30 Jul 2021 04:28:49 +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 B5CD760506\n\tfor ;\n\tFri, 30 Jul 2021 04:28:47 +0200 (CEST)","from pendragon.ideasonboard.com (62-78-145-57.bb.dnainternet.fi\n\t[62.78.145.57])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 2951B89B;\n\tFri, 30 Jul 2021 04:28:47 +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=\"UvCOJwOY\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1627612127;\n\tbh=Lz9SeeKz7nd1Ur5sWcQfVxNOG+whKNbWGyWGP0m/dC4=;\n\th=Date:From:To:Cc:Subject:References:In-Reply-To:From;\n\tb=UvCOJwOYMhSINYte44ySH7FF3+i7W/mi6Nmq3eQ795CE9I9vNJQma/4tbEcmhp1q/\n\tEc/eXF6aIXZBt4sTCURNZ56xykqlHjDYSFxiHZ91kdIW3O3+2SfCqlSAzhmzioZQ2n\n\tqFqNjyTXUmrnL7Mmfakvaae2FxW3SJo9jnIfrL0Q=","Date":"Fri, 30 Jul 2021 05:28:39 +0300","From":"Laurent Pinchart ","To":"Jacopo Mondi ","Message-ID":"","References":"<20210723040036.32346-1-laurent.pinchart@ideasonboard.com>\n\t<20210723040036.32346-2-laurent.pinchart@ideasonboard.com>\n\t<20210729200542.6yizqyuzfdpnqvsz@uno.localdomain>","MIME-Version":"1.0","Content-Type":"text/plain; charset=utf-8","Content-Disposition":"inline","In-Reply-To":"<20210729200542.6yizqyuzfdpnqvsz@uno.localdomain>","Subject":"Re: [libcamera-devel] [RFC PATCH 01/17] libcamera: base: class:\n\tDocument Extensible::_d() functions","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","Cc":"libcamera-devel@lists.libcamera.org","Errors-To":"libcamera-devel-bounces@lists.libcamera.org","Sender":"\"libcamera-devel\" "}}]