[{"id":37649,"web_url":"https://patchwork.libcamera.org/comment/37649/","msgid":"","date":"2026-01-14T11:24:27","subject":"Re: [PATCH 18/36] libcamera: yaml_object: Miscellaneous\n\tdocumentation improvements","submitter":{"id":216,"url":"https://patchwork.libcamera.org/api/people/216/","name":"Barnabás Pőcze","email":"barnabas.pocze@ideasonboard.com"},"content":"2026. 01. 13. 1:07 keltezéssel, Laurent Pinchart írta:\n> Fix a few documentation issues:\n> \n> - Drop unneeded \\fn\n> - Sort \\brief and \\tparam correctly\n> - Add missing \\tparam and \\param\n> - Explain the T and U template parameters for get()\n> - Standardize the naming of dictionary keys as \"key\"\n> - Fix typo\n> \n> Signed-off-by: Laurent Pinchart \n> ---> src/libcamera/yaml_object.cpp | 29 ++++++++++++++++-------------\n> 1 file changed, 16 insertions(+), 13 deletions(-)\n> \n> diff --git a/src/libcamera/yaml_object.cpp b/src/libcamera/yaml_object.cpp\n> index 5e92189fdb8e..4328ccbff8f1 100644\n> --- a/src/libcamera/yaml_object.cpp\n> +++ b/src/libcamera/yaml_object.cpp\n> @@ -81,7 +81,6 @@ YamlObject::~YamlObject() = default;\n> */\n> \n> /**\n> - * \\fn YamlObject::size()\n> * \\brief Retrieve the number of elements in a dictionary or list YamlObject\n> *\n> * This function retrieves the size of the YamlObject, defined as the number of\n> @@ -104,8 +103,8 @@ std::size_t YamlObject::size() const\n> \n> /**\n> * \\fn template YamlObject::get() const\n> - * \\tparam T Type of the value\n> * \\brief Parse the YamlObject as a \\a T value\n> + * \\tparam T Type of the value\n> *\n> * This function parses the value of the YamlObject as a \\a T object, and\n> * returns the value. If parsing fails (usually because the YamlObject doesn't\n> @@ -120,11 +119,14 @@ std::size_t YamlObject::size() const\n> /**\n> * \\fn template YamlObject::get(U &&defaultValue) const\n> * \\brief Parse the YamlObject as a \\a T value\n> + * \\tparam T Type of the value\n> + * \\tparam U Type of the default value\n> * \\param[in] defaultValue The default value when failing to parse\n> *\n> * This function parses the value of the YamlObject as a \\a T object, and\n> * returns the value. If parsing fails (usually because the YamlObject doesn't\n> - * store a \\a T value), the \\a defaultValue is returned.\n> + * store a \\a T value), the \\a defaultValue is returned. Type \\a U must be\n> + * convertible to type \\a T.\n> *\n> * Unlike the get() function, this overload does not support std::vector for the\n> * type \\a T.\n> @@ -135,6 +137,7 @@ std::size_t YamlObject::size() const\n> /**\n> * \\fn template YamlObject::set(T &&value)\n> * \\brief Set the value of a YamlObject\n> + * \\tparam T Type of the value\n> * \\param[in] value The value\n> *\n> * This function sets the value stored in a YamlObject to \\a value. The value is\n> @@ -363,8 +366,8 @@ template struct YamlObject::Accessor>;\n> */\n> \n> /**\n> - * \\fn YamlObject::operator[](std::size_t index) const\n> * \\brief Retrieve the element from list YamlObject by index\n> + * \\param[in] index The element index\n> *\n> * This function retrieves an element of the YamlObject. Only YamlObject\n> * instances of List type associate elements with index, calling this function\n> @@ -382,13 +385,13 @@ const YamlObject &YamlObject::operator[](std::size_t index) const\n> }\n> \n> /**\n> - * \\fn YamlObject::contains()\n> * \\brief Check if an element of a dictionary exists\n> + * \\param[in] key The element key\n> *\n> - * This function check if the YamlObject contains an element. Only YamlObject\n> - * instances of Dictionary type associate elements with names, calling this\n> - * function on other types of instances is invalid and results in undefined\n> - * behaviour.\n> + * This function check if the YamlObject contains an element for the given \\a\n checks\n\nReviewed-by: Barnabás Pőcze \n\n\n> + * key. Only YamlObject instances of Dictionary type associate elements with\n> + * keys, calling this function on other types of instances is invalid and\n> + * results in undefined behaviour.\n> *\n> * \\return True if an element exists, false otherwise\n> */\n> @@ -398,11 +401,11 @@ bool YamlObject::contains(std::string_view key) const\n> }\n> \n> /**\n> - * \\fn YamlObject::operator[](std::string_view key) const\n> - * \\brief Retrieve a member by name from the dictionary\n> + * \\brief Retrieve a member by key from the dictionary\n> + * \\param[in] key The element key\n> *\n> - * This function retrieve a member of a YamlObject by name. Only YamlObject\n> - * instances of Dictionary type associate elements with names, calling this\n> + * This function retrieves a member of a YamlObject by \\a key. Only YamlObject\n> + * instances of Dictionary type associate elements with keys, calling this\n> * function on other types of instances or with a nonexistent key results in an\n> * empty object.\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 D832EBDCBF\n\tfor ;\n\tWed, 14 Jan 2026 11:24:33 +0000 (UTC)","from lancelot.ideasonboard.com (localhost [IPv6:::1])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTP id 2269561F9F;\n\tWed, 14 Jan 2026 12:24:33 +0100 (CET)","from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 7983261F9F\n\tfor ;\n\tWed, 14 Jan 2026 12:24:31 +0100 (CET)","from [192.168.33.18] (185.221.143.114.nat.pool.zt.hu\n\t[185.221.143.114])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id BCC5F24A;\n\tWed, 14 Jan 2026 12:24:04 +0100 (CET)"],"Authentication-Results":"lancelot.ideasonboard.com; dkim=pass (1024-bit key;\n\tunprotected) header.d=ideasonboard.com header.i=@ideasonboard.com\n\theader.b=\"I1YGskgn\"; dkim-atps=neutral","DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1768389844;\n\tbh=dvhQH2boyYDIOGXWJDYuIy62RmL3rPaRf0i9jieEUxI=;\n\th=Date:Subject:To:References:From:In-Reply-To:From;\n\tb=I1YGskgnzwlHAYLDhfeuZvB3s4OUhC8aAQATO7+H2ZVQxsEA3ld8PpP/sew4ZrGJc\n\tWtltsIPCXsLlaXlX/6KV8DMm+6jxdVj5pE6KFOMn8SKgDKAU7MbHuOOm0GK7RUlkc9\n\t9vTCpzYWAH0ov6WUwC3tz5nlmiu1ruoRvn9FwkZE=","Message-ID":"","Date":"Wed, 14 Jan 2026 12:24:27 +0100","MIME-Version":"1.0","User-Agent":"Mozilla Thunderbird","Subject":"Re: [PATCH 18/36] libcamera: yaml_object: Miscellaneous\n\tdocumentation improvements","To":"Laurent Pinchart ,\n\tlibcamera-devel@lists.libcamera.org","References":"<20260113000808.15395-1-laurent.pinchart@ideasonboard.com>\n\t<20260113000808.15395-19-laurent.pinchart@ideasonboard.com>","From":"=?utf-8?q?Barnab=C3=A1s_P=C5=91cze?= ","Content-Language":"en-US, hu-HU","In-Reply-To":"<20260113000808.15395-19-laurent.pinchart@ideasonboard.com>","Content-Type":"text/plain; charset=UTF-8; format=flowed","Content-Transfer-Encoding":"8bit","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\" "}}]