[{"id":271,"web_url":"https://patchwork.libcamera.org/comment/271/","msgid":"<20190109154150.GC24252@bigcity.dyn.berto.se>","date":"2019-01-09T15:41:50","subject":"Re: [libcamera-devel] [PATCH] libcamera: Document missing\n\tparameters and return values","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 patch.\n\nOn 2019-01-08 16:46:42 +0200, Laurent Pinchart wrote:\n> Several functions are missing documentation for some of them parameters\n> and/or for their return value. Fix this.\n> \n> Signed-off-by: Laurent Pinchart \n\nReviewed-by: Niklas Söderlund \n\n> ---\n> src/libcamera/device_enumerator.cpp | 3 +++\n> src/libcamera/log.cpp | 7 +++++++\n> src/libcamera/pipeline_handler.cpp | 8 +++++---\n> src/libcamera/signal.cpp | 5 +++++\n> 4 files changed, 20 insertions(+), 3 deletions(-)\n> \n> diff --git a/src/libcamera/device_enumerator.cpp b/src/libcamera/device_enumerator.cpp\n> index c088f3e5d243..f1d016db64a0 100644\n> --- a/src/libcamera/device_enumerator.cpp\n> +++ b/src/libcamera/device_enumerator.cpp\n> @@ -124,6 +124,9 @@ bool DeviceMatch::match(const MediaDevice *device) const\n> * implementations may be needed. This function creates the best enumerator for\n> * the operating system based on the available resources. Not all different\n> * enumerator types are guaranteed to support all features.\n> + *\n> + * \\return A pointer to the newly created device enumerator on success, or\n> + * nullptr if an error occurs\n> */\n> DeviceEnumerator *DeviceEnumerator::create()\n> {\n> diff --git a/src/libcamera/log.cpp b/src/libcamera/log.cpp\n> index c1ec55618ea3..281e31d963f5 100644\n> --- a/src/libcamera/log.cpp\n> +++ b/src/libcamera/log.cpp\n> @@ -90,6 +90,11 @@ static const char *log_severity_name(LogSeverity severity)\n> */\n> \n> /**\n> + * \\param fileName The file name where the message is logged from\n> + * \\param line The line number where the message is logged from\n> + * \\param severity The log message severity, controlling how the message will be\n> + * displayed\n> + *\n> * Create a log message pertaining to line \\a line of file \\a fileName. The\n> * \\a severity argument sets the message severity to control whether it will be\n> * output or dropped.\n> @@ -130,6 +135,8 @@ LogMessage::~LogMessage()\n> * Data is added to a LogMessage through the stream returned by this function.\n> * The stream implements the std::ostream API and can be used for logging as\n> * std::cout.\n> + *\n> + * \\return A reference to the log message stream\n> */\n> \n> } /* namespace libcamera */\n> diff --git a/src/libcamera/pipeline_handler.cpp b/src/libcamera/pipeline_handler.cpp\n> index 093821d4c471..ee7694879848 100644\n> --- a/src/libcamera/pipeline_handler.cpp\n> +++ b/src/libcamera/pipeline_handler.cpp\n> @@ -36,11 +36,13 @@ namespace libcamera {\n> /**\n> * \\fn PipelineHandler::match(DeviceEnumerator *enumerator)\n> * \\brief Match media devices and create camera instances\n> + * \\param enumerator The enumerator providing all media devices found in the\n> + * system\n> *\n> * This function is the main entry point of the pipeline handler. It is called\n> - * by the device enumerator with the enumerator passed as an argument. It shall\n> - * acquire from the enumerator all the media devices it needs for a single\n> - * pipeline and create one or multiple Camera instances.\n> + * by the device enumerator with the \\a enumerator passed as an argument. It\n> + * shall acquire from the \\a enumerator all the media devices it needs for a\n> + * single pipeline and create one or multiple Camera instances.\n> *\n> * If all media devices needed by the pipeline handler are found, they must all\n> * be acquired by a call to MediaDevice::acquire(). This function shall then\n> diff --git a/src/libcamera/signal.cpp b/src/libcamera/signal.cpp\n> index 0fd3bb2a34a1..51536dc5fdd0 100644\n> --- a/src/libcamera/signal.cpp\n> +++ b/src/libcamera/signal.cpp\n> @@ -58,21 +58,26 @@ namespace libcamera {\n> /**\n> * \\fn Signal::disconnect(T *object)\n> * \\brief Disconnect the signal from all slots of the \\a object\n> + * \\param object The object pointer whose slots to disconnect\n> */\n> \n> /**\n> * \\fn Signal::disconnect(T *object, void(T::*func)(Args...))\n> * \\brief Disconnect the signal from the \\a object slot member function \\a func\n> + * \\param object The object pointer whose slots to disconnect\n> + * \\param func The slot member function to disconnect\n> */\n> \n> /**\n> * \\fn Signal::disconnect(void(*func)(Args...))\n> * \\brief Disconnect the signal from the slot static function \\a func\n> + * \\param func The slot static function to disconnect\n> */\n> \n> /**\n> * \\fn Signal::emit(Args... args)\n> * \\brief Emit the signal and call all connected slots\n> + * \\param args The arguments passed to the connected slots\n> *\n> * Emitting a signal calls all connected slots synchronously and sequentially in\n> * the order the slots have been connected. The arguments passed to the emit()\n> -- \n> Regards,\n> \n> Laurent Pinchart\n> \n> _______________________________________________\n> libcamera-devel mailing list\n> libcamera-devel@lists.libcamera.org\n> https://lists.libcamera.org/listinfo/libcamera-devel","headers":{"Return-Path":"","Received":["from mail-lj1-x243.google.com (mail-lj1-x243.google.com\n\t[IPv6:2a00:1450:4864:20::243])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id F105160B2D\n\tfor ;\n\tWed, 9 Jan 2019 16:41:52 +0100 (CET)","by mail-lj1-x243.google.com with SMTP id k15-v6so6852980ljc.8\n\tfor ;\n\tWed, 09 Jan 2019 07:41:52 -0800 (PST)","from localhost (89-233-230-99.cust.bredband2.com. [89.233.230.99])\n\tby smtp.gmail.com with ESMTPSA id\n\tm13-v6sm14954852ljg.56.2019.01.09.07.41.51\n\t(version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256);\n\tWed, 09 Jan 2019 07:41:51 -0800 (PST)"],"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\t:user-agent; bh=35nwLisFs/lr+q1ImcdAFgBhfbZbmcZQh+q4XDmCjjk=;\n\tb=kc3+PkhRC141DN+tJ013JfJs3tnHdeXCPPyWIlfv7WBjt1AxBZAM0YQ+7wWpUC1V+B\n\tZsvVunEH54EpC/BL6IJBU5QeMNWsFYDKTd0GvYRLSx0/1mFT9ZA78RveiIOIgaFeTT/t\n\tAdOzsI0ERaxifdDsVF1yQ4Z3HV1L7ZwQwb5clxo6zllBbzZrY7TpwBxOlWwKCK9F3LYM\n\tBS/okPA9dkkubvgNXwS7BWJcRaR7dByPvYMurB2T1s6Oz0Yv28FPsmuS5SJTW2uglcPD\n\tRPnyAGBb4MVhhnGY2rfDqPVquWBo7ox5vkpfi+XUuQRFHwBpfZE6rbKAR1i2USNU2GdI\n\t42UA==","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:user-agent;\n\tbh=35nwLisFs/lr+q1ImcdAFgBhfbZbmcZQh+q4XDmCjjk=;\n\tb=ZUp+7RliE4Ljsf5/TU4/CdZLesiyj7ECDugk4u0tNz87Gws9A3Wbs+Y/jNPoHJsXmv\n\tFGhPS7K/FIPojjeLDLqFp1h3k6y/BY3cJuXtrgZTj+59lcbUiAG341THAmeRrMnRkiE/\n\tx6Jdi7J/NF7Psqwp8fL7qbEv4Ip5vLW2uW2nqJFbBFpExyXFNNjldT4dKmDJcCyKRJvj\n\tYxTStkTLXg+fV1z6aAUd4QT6lEDDFMNeBGgrueOsIH6akrBcFeTWTpCYuHgHPQI2SP0A\n\tvK9V9W8W5dKP8mQNgbNZW1KSzjOWFgfPxTqCELMZXRP8MT9MWFwqcH6eToUkUVZx+S4e\n\tmNAg==","X-Gm-Message-State":"AJcUukdMNxc7uAzziuyTCDxVafsCjIFe49kWr/x9236uqDi5o7NVzqKT\n\tEH2HHUx0c5ESC01oAbteGCJm6jcKDjs=","X-Google-Smtp-Source":"ALg8bN6OY4H8Uu6VaDTNjnqVwi5yDfCN3lkotpaMwp5I0KqHrDOjRnHpUDe3CTvsvycIWMk6eLM+KQ==","X-Received":"by 2002:a2e:3012:: with SMTP id\n\tw18-v6mr3675623ljw.75.1547048512253; \n\tWed, 09 Jan 2019 07:41:52 -0800 (PST)","Date":"Wed, 9 Jan 2019 16:41:50 +0100","From":"Niklas =?iso-8859-1?q?S=F6derlund?= ","To":"Laurent Pinchart ","Cc":"libcamera-devel@lists.libcamera.org","Message-ID":"<20190109154150.GC24252@bigcity.dyn.berto.se>","References":"<20190108144642.10611-1-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":"<20190108144642.10611-1-laurent.pinchart@ideasonboard.com>","User-Agent":"Mutt/1.10.1 (2018-07-13)","Subject":"Re: [libcamera-devel] [PATCH] libcamera: Document missing\n\tparameters and return values","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.23","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","X-List-Received-Date":"Wed, 09 Jan 2019 15:41:53 -0000"}}]