[{"id":256,"web_url":"https://patchwork.libcamera.org/comment/256/","msgid":"<2319068.959v6Kqr0x@avalon>","date":"2019-01-08T14:43:13","subject":"Re: [libcamera-devel] [PATCH 2/2] [RFC] Documentation: Enable\n\tparameter documentation warnings","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"content":"Hi Kieran,\n\nThank you for the patch.\n\nOn Tuesday, 8 January 2019 15:21:06 EET Kieran Bingham wrote:\n> Enable WARN_NO_PARAMDOC to guide us towards more complete documentation.\n> \n> Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>\n> \n> ---\n> This currently generates the following extra warnings:\n> \n>   src/libcamera/pipeline/vimc.cpp:17: warning: Compound\n> libcamera::PipeHandlerVimc is not documented.\n> include/libcamera/camera_manager.h:20: warning: Compound\n> libcamera::CameraManager is not documented.\n> src/libcamera/include/device_enumerator.h:37: warning: return type of\n> member libcamera::DeviceEnumerator::create is not documented\n> src/libcamera/include/log.h:26: warning: parameters of member\n> libcamera::LogMessage::LogMessage are not (all) documented\n> src/libcamera/include/log.h:24: warning: parameters of member\n> libcamera::LogMessage::LogMessage are not (all) documented\n> src/libcamera/include/log.h:29: warning: return type of member\n> libcamera::LogMessage::stream is not documented\n> src/libcamera/include/media_object.h:94: warning: parameters of member\n> libcamera::MediaEntity::MediaDevice are not (all) documented\n> src/libcamera/include/media_object.h:43: warning: parameters of member\n> libcamera::MediaLink::MediaDevice are not (all) documented\n> src/libcamera/include/media_object.h:27: warning: parameters of member\n> libcamera::MediaObject::MediaDevice are not (all) documented\n> src/libcamera/include/media_object.h:66: warning: parameters of member\n> libcamera::MediaPad::MediaDevice are not (all) documented\n> src/libcamera/pipeline/vimc.cpp:22: warning: parameters of member\n> libcamera::PipeHandlerVimc::match are not (all) documented\n> src/libcamera/include/pipeline_handler.h:25: warning: parameters of member\n> libcamera::PipelineHandler::match are not (all) documented\n\nI think this is generally useful, but only if we can document all parameters. \nI had a quick look, and we get a warning for\n\n\tLogMessage(const LogMessage&) = delete;\n\nWe also get warnings for\n\n\tfriend class MediaDevice;\n\nin media_object.h.\n\nUnless we can instruct doxygen to ignore these, I don't think we should enable \nparameter warnings by default as we wouldn't be able to achieve a clean build.\n\n>  Documentation/Doxyfile.in | 2 +-\n>  1 file changed, 1 insertion(+), 1 deletion(-)\n> \n> diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in\n> index 335664dbcbf0..9dfab0852a9d 100644\n> --- a/Documentation/Doxyfile.in\n> +++ b/Documentation/Doxyfile.in\n> @@ -757,7 +757,7 @@ WARN_IF_DOC_ERROR      = YES\n>  # parameter documentation, but not about the absence of documentation.\n>  # The default value is: NO.\n> \n> -WARN_NO_PARAMDOC       = NO\n> +WARN_NO_PARAMDOC       = YES\n> \n>  # If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop\n> when # a warning is encountered.","headers":{"Return-Path":"<laurent.pinchart@ideasonboard.com>","Received":["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 B74C960B2E\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tTue,  8 Jan 2019 15:42:05 +0100 (CET)","from avalon.localnet (dfj612ybrt5fhg77mgycy-3.rev.dnainternet.fi\n\t[IPv6:2001:14ba:21f5:5b00:2e86:4862:ef6a:2804])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 41ABE586;\n\tTue,  8 Jan 2019 15:42:05 +0100 (CET)"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1546958525;\n\tbh=8ZJf8GOlz1CNnK5T6MHAljVWMdoWw7fkaADe1tpwPj4=;\n\th=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n\tb=EZbl0y81cV4kc0mkBRVUWQRPeQk0IdfwWyZts431TsqTMOdcFn5gZBfTps0rYDgBE\n\tRsTBvumnT2ynAObUMMtFcO65ppShTm20+TKsjVNa2CFxCPi3tZyPAThwXqORtAVulw\n\tj4Saf1AqtdSMrHhVqy7NJAKDyXgX76R1vH2zYYf8=","From":"Laurent Pinchart <laurent.pinchart@ideasonboard.com>","To":"libcamera-devel@lists.libcamera.org","Date":"Tue, 08 Jan 2019 16:43:13 +0200","Message-ID":"<2319068.959v6Kqr0x@avalon>","Organization":"Ideas on Board Oy","In-Reply-To":"<20190108132106.24906-3-kieran.bingham@ideasonboard.com>","References":"<20190108132106.24906-1-kieran.bingham@ideasonboard.com>\n\t<20190108132106.24906-3-kieran.bingham@ideasonboard.com>","MIME-Version":"1.0","Content-Transfer-Encoding":"7Bit","Content-Type":"text/plain; charset=\"us-ascii\"","Subject":"Re: [libcamera-devel] [PATCH 2/2] [RFC] Documentation: Enable\n\tparameter documentation warnings","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.23","Precedence":"list","List-Id":"<libcamera-devel.lists.libcamera.org>","List-Unsubscribe":"<https://lists.libcamera.org/options/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=unsubscribe>","List-Archive":"<https://lists.libcamera.org/pipermail/libcamera-devel/>","List-Post":"<mailto:libcamera-devel@lists.libcamera.org>","List-Help":"<mailto:libcamera-devel-request@lists.libcamera.org?subject=help>","List-Subscribe":"<https://lists.libcamera.org/listinfo/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=subscribe>","X-List-Received-Date":"Tue, 08 Jan 2019 14:42:05 -0000"}},{"id":281,"web_url":"https://patchwork.libcamera.org/comment/281/","msgid":"<e37c445f-8acc-eaf9-4b62-2fdb54a2d3af@ideasonboard.com>","date":"2019-01-11T12:22:29","subject":"Re: [libcamera-devel] [PATCH 2/2] [RFC] Documentation: Enable\n\tparameter documentation warnings","submitter":{"id":4,"url":"https://patchwork.libcamera.org/api/people/4/","name":"Kieran Bingham","email":"kieran.bingham@ideasonboard.com"},"content":"Hi Laurent,\n\nOn 08/01/2019 14:43, Laurent Pinchart wrote:\n> Hi Kieran,\n> \n> Thank you for the patch.\n> \n> On Tuesday, 8 January 2019 15:21:06 EET Kieran Bingham wrote:\n>> Enable WARN_NO_PARAMDOC to guide us towards more complete documentation.\n>>\n>> Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>\n>>\n>> ---\n>> This currently generates the following extra warnings:\n>>\n>>   src/libcamera/pipeline/vimc.cpp:17: warning: Compound\n>> libcamera::PipeHandlerVimc is not documented.\n>> include/libcamera/camera_manager.h:20: warning: Compound\n>> libcamera::CameraManager is not documented.\n>> src/libcamera/include/device_enumerator.h:37: warning: return type of\n>> member libcamera::DeviceEnumerator::create is not documented\n>> src/libcamera/include/log.h:26: warning: parameters of member\n>> libcamera::LogMessage::LogMessage are not (all) documented\n>> src/libcamera/include/log.h:24: warning: parameters of member\n>> libcamera::LogMessage::LogMessage are not (all) documented\n>> src/libcamera/include/log.h:29: warning: return type of member\n>> libcamera::LogMessage::stream is not documented\n>> src/libcamera/include/media_object.h:94: warning: parameters of member\n>> libcamera::MediaEntity::MediaDevice are not (all) documented\n>> src/libcamera/include/media_object.h:43: warning: parameters of member\n>> libcamera::MediaLink::MediaDevice are not (all) documented\n>> src/libcamera/include/media_object.h:27: warning: parameters of member\n>> libcamera::MediaObject::MediaDevice are not (all) documented\n>> src/libcamera/include/media_object.h:66: warning: parameters of member\n>> libcamera::MediaPad::MediaDevice are not (all) documented\n>> src/libcamera/pipeline/vimc.cpp:22: warning: parameters of member\n>> libcamera::PipeHandlerVimc::match are not (all) documented\n>> src/libcamera/include/pipeline_handler.h:25: warning: parameters of member\n>> libcamera::PipelineHandler::match are not (all) documented\n> \n> I think this is generally useful, but only if we can document all parameters. \n> I had a quick look, and we get a warning for\n> \n> \tLogMessage(const LogMessage&) = delete;\n> \n> We also get warnings for\n> \n> \tfriend class MediaDevice;\n> \n> in media_object.h.\n> \n> Unless we can instruct doxygen to ignore these, I don't think we should enable \n> parameter warnings by default as we wouldn't be able to achieve a clean build.\n\nLets drop this patch for now.\n\nI'll submit a patch next to quieten the sphinx build, then consider this\ntopic complete for the moment.\n\n--\nKieran\n\n\n> \n>>  Documentation/Doxyfile.in | 2 +-\n>>  1 file changed, 1 insertion(+), 1 deletion(-)\n>>\n>> diff --git a/Documentation/Doxyfile.in b/Documentation/Doxyfile.in\n>> index 335664dbcbf0..9dfab0852a9d 100644\n>> --- a/Documentation/Doxyfile.in\n>> +++ b/Documentation/Doxyfile.in\n>> @@ -757,7 +757,7 @@ WARN_IF_DOC_ERROR      = YES\n>>  # parameter documentation, but not about the absence of documentation.\n>>  # The default value is: NO.\n>>\n>> -WARN_NO_PARAMDOC       = NO\n>> +WARN_NO_PARAMDOC       = YES\n>>\n>>  # If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop\n>> when # a warning is encountered.\n>","headers":{"Return-Path":"<kieran.bingham@ideasonboard.com>","Received":["from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id C6AB7600CC\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tFri, 11 Jan 2019 13:22:35 +0100 (CET)","from [192.168.0.21]\n\t(cpc89242-aztw30-2-0-cust488.18-1.cable.virginm.net [86.31.129.233])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 0F92C547;\n\tFri, 11 Jan 2019 13:22:31 +0100 (CET)"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1547209352;\n\tbh=tYqStyrFBJv/RgRWFm0kvyqI5E+2vXEX+jXhScSRU1Y=;\n\th=Reply-To:Subject:To:References:From:Date:In-Reply-To:From;\n\tb=ZfxbYCZ0Nru6HmBO9amX2uVYN8yCpE+gVbimmjF+zI/6qlEPqsFUsxoSrViu8zJ2Z\n\tWitd4HFMVv/qFAUjGntfqVEH5B27K/y3Ey86P36ogTUm8SW6n+naXNOwVIrweofy7o\n\t5YMYEY7NtKUT4Io68axfAwnpKj5pGEWbYFpqpY6g=","Reply-To":"kieran.bingham@ideasonboard.com","To":"Laurent Pinchart <laurent.pinchart@ideasonboard.com>,\n\tlibcamera-devel@lists.libcamera.org","References":"<20190108132106.24906-1-kieran.bingham@ideasonboard.com>\n\t<20190108132106.24906-3-kieran.bingham@ideasonboard.com>\n\t<2319068.959v6Kqr0x@avalon>","From":"Kieran Bingham <kieran.bingham@ideasonboard.com>","Openpgp":"preference=signencrypt","Autocrypt":"addr=kieran.bingham@ideasonboard.com; keydata=\n\tmQINBFYE/WYBEACs1PwjMD9rgCu1hlIiUA1AXR4rv2v+BCLUq//vrX5S5bjzxKAryRf0uHat\n\tV/zwz6hiDrZuHUACDB7X8OaQcwhLaVlq6byfoBr25+hbZG7G3+5EUl9cQ7dQEdvNj6V6y/SC\n\trRanWfelwQThCHckbobWiQJfK9n7rYNcPMq9B8e9F020LFH7Kj6YmO95ewJGgLm+idg1Kb3C\n\tpotzWkXc1xmPzcQ1fvQMOfMwdS+4SNw4rY9f07Xb2K99rjMwZVDgESKIzhsDB5GY465sCsiQ\n\tcSAZRxqE49RTBq2+EQsbrQpIc8XiffAB8qexh5/QPzCmR4kJgCGeHIXBtgRj+nIkCJPZvZtf\n\tKr2EAbc6tgg6DkAEHJb+1okosV09+0+TXywYvtEop/WUOWQ+zo+Y/OBd+8Ptgt1pDRyOBzL8\n\tRXa8ZqRf0Mwg75D+dKntZeJHzPRJyrlfQokngAAs4PaFt6UfS+ypMAF37T6CeDArQC41V3ko\n\tlPn1yMsVD0p+6i3DPvA/GPIksDC4owjnzVX9kM8Zc5Cx+XoAN0w5Eqo4t6qEVbuettxx55gq\n\t8K8FieAjgjMSxngo/HST8TpFeqI5nVeq0/lqtBRQKumuIqDg+Bkr4L1V/PSB6XgQcOdhtd36\n\tOe9X9dXB8YSNt7VjOcO7BTmFn/Z8r92mSAfHXpb07YJWJosQOQARAQABtDBLaWVyYW4gQmlu\n\tZ2hhbSA8a2llcmFuLmJpbmdoYW1AaWRlYXNvbmJvYXJkLmNvbT6JAkAEEwEKACoCGwMFCwkI\n\tBwIGFQgJCgsCBBYCAwECHgECF4ACGQEFAlnDk/gFCQeA/YsACgkQoR5GchCkYf3X5w/9EaZ7\n\tcnUcT6dxjxrcmmMnfFPoQA1iQXr/MXQJBjFWfxRUWYzjvUJb2D/FpA8FY7y+vksoJP7pWDL7\n\tQTbksdwzagUEk7CU45iLWL/CZ/knYhj1I/+5LSLFmvZ/5Gf5xn2ZCsmg7C0MdW/GbJ8IjWA8\n\t/LKJSEYH8tefoiG6+9xSNp1p0Gesu3vhje/GdGX4wDsfAxx1rIYDYVoX4bDM+uBUQh7sQox/\n\tR1bS0AaVJzPNcjeC14MS226mQRUaUPc9250aj44WmDfcg44/kMsoLFEmQo2II9aOlxUDJ+x1\n\txohGbh9mgBoVawMO3RMBihcEjo/8ytW6v7xSF+xP4Oc+HOn7qebAkxhSWcRxQVaQYw3S9iZz\n\t2iA09AXAkbvPKuMSXi4uau5daXStfBnmOfalG0j+9Y6hOFjz5j0XzaoF6Pln0jisDtWltYhP\n\tX9LjFVhhLkTzPZB/xOeWGmsG4gv2V2ExbU3uAmb7t1VSD9+IO3Km4FtnYOKBWlxwEd8qOFpS\n\tjEqMXURKOiJvnw3OXe9MqG19XdeENA1KyhK5rqjpwdvPGfSn2V+SlsdJA0DFsobUScD9qXQw\n\tOvhapHe3XboK2+Rd7L+g/9Ud7ZKLQHAsMBXOVJbufA1AT+IaOt0ugMcFkAR5UbBg5+dZUYJj\n\t1QbPQcGmM3wfvuaWV5+SlJ+WeKIb8ta5Ag0EVgT9ZgEQAM4o5G/kmruIQJ3K9SYzmPishRHV\n\tDcUcvoakyXSX2mIoccmo9BHtD9MxIt+QmxOpYFNFM7YofX4lG0ld8H7FqoNVLd/+a0yru5Cx\n\tadeZBe3qr1eLns10Q90LuMo7/6zJhCW2w+HE7xgmCHejAwuNe3+7yt4QmwlSGUqdxl8cgtS1\n\tPlEK93xXDsgsJj/bw1EfSVdAUqhx8UQ3aVFxNug5OpoX9FdWJLKROUrfNeBE16RLrNrq2ROc\n\tiSFETpVjyC/oZtzRFnwD9Or7EFMi76/xrWzk+/b15RJ9WrpXGMrttHUUcYZEOoiC2lEXMSAF\n\tSSSj4vHbKDJ0vKQdEFtdgB1roqzxdIOg4rlHz5qwOTynueiBpaZI3PHDudZSMR5Fk6QjFooE\n\tXTw3sSl/km/lvUFiv9CYyHOLdygWohvDuMkV/Jpdkfq8XwFSjOle+vT/4VqERnYFDIGBxaRx\n\tkoBLfNDiiuR3lD8tnJ4A1F88K6ojOUs+jndKsOaQpDZV6iNFv8IaNIklTPvPkZsmNDhJMRHH\n\tIu60S7BpzNeQeT4yyY4dX9lC2JL/LOEpw8DGf5BNOP1KgjCvyp1/KcFxDAo89IeqljaRsCdP\n\t7WCIECWYem6pLwaw6IAL7oX+tEqIMPph/G/jwZcdS6Hkyt/esHPuHNwX4guqTbVEuRqbDzDI\n\t2DJO5FbxABEBAAGJAiUEGAEKAA8CGwwFAlnDlGsFCQeA/gIACgkQoR5GchCkYf1yYRAAq+Yo\n\tnbf9DGdK1kTAm2RTFg+w9oOp2Xjqfhds2PAhFFvrHQg1XfQR/UF/SjeUmaOmLSczM0s6XMeO\n\tVcE77UFtJ/+hLo4PRFKm5X1Pcar6g5m4xGqa+Xfzi9tRkwC29KMCoQOag1BhHChgqYaUH3yo\n\tUzaPwT/fY75iVI+yD0ih/e6j8qYvP8pvGwMQfrmN9YB0zB39YzCSdaUaNrWGD3iCBxg6lwSO\n\tLKeRhxxfiXCIYEf3vwOsP3YMx2JkD5doseXmWBGW1U0T/oJF+DVfKB6mv5UfsTzpVhJRgee7\n\t4jkjqFq4qsUGxcvF2xtRkfHFpZDbRgRlVmiWkqDkT4qMA+4q1y/dWwshSKi/uwVZNycuLsz+\n\t+OD8xPNCsMTqeUkAKfbD8xW4LCay3r/dD2ckoxRxtMD9eOAyu5wYzo/ydIPTh1QEj9SYyvp8\n\tO0g6CpxEwyHUQtF5oh15O018z3ZLztFJKR3RD42VKVsrnNDKnoY0f4U0z7eJv2NeF8xHMuiU\n\tRCIzqxX1GVYaNkKTnb/Qja8hnYnkUzY1Lc+OtwiGmXTwYsPZjjAaDX35J/RSKAoy5wGo/YFA\n\tJxB1gWThL4kOTbsqqXj9GLcyOImkW0lJGGR3o/fV91Zh63S5TKnf2YGGGzxki+ADdxVQAm+Q\n\tsbsRB8KNNvVXBOVNwko86rQqF9drZuw=","Organization":"Ideas on Board","Message-ID":"<e37c445f-8acc-eaf9-4b62-2fdb54a2d3af@ideasonboard.com>","Date":"Fri, 11 Jan 2019 12:22:29 +0000","User-Agent":"Mozilla/5.0 (X11; Linux x86_64; rv:60.0) Gecko/20100101\n\tThunderbird/60.2.1","MIME-Version":"1.0","In-Reply-To":"<2319068.959v6Kqr0x@avalon>","Content-Type":"text/plain; charset=utf-8","Content-Language":"en-GB","Content-Transfer-Encoding":"7bit","Subject":"Re: [libcamera-devel] [PATCH 2/2] [RFC] Documentation: Enable\n\tparameter documentation warnings","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.23","Precedence":"list","List-Id":"<libcamera-devel.lists.libcamera.org>","List-Unsubscribe":"<https://lists.libcamera.org/options/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=unsubscribe>","List-Archive":"<https://lists.libcamera.org/pipermail/libcamera-devel/>","List-Post":"<mailto:libcamera-devel@lists.libcamera.org>","List-Help":"<mailto:libcamera-devel-request@lists.libcamera.org?subject=help>","List-Subscribe":"<https://lists.libcamera.org/listinfo/libcamera-devel>,\n\t<mailto:libcamera-devel-request@lists.libcamera.org?subject=subscribe>","X-List-Received-Date":"Fri, 11 Jan 2019 12:22:36 -0000"}}]