[{"id":295,"web_url":"https://patchwork.libcamera.org/comment/295/","msgid":"<20190114093817.7pwpgp3rwr4hzapn@uno.localdomain>","date":"2019-01-14T09:38:17","subject":"Re: [libcamera-devel] [PATCH 2/3] libcamera: camera_manager:\n\tImprove class documentation","submitter":{"id":3,"url":"https://patchwork.libcamera.org/api/people/3/","name":"Jacopo Mondi","email":"jacopo@jmondi.org"},"content":"Hi Laurent,\n\nOn Sat, Jan 12, 2019 at 04:46:18PM +0200, Laurent Pinchart wrote:\n> Move documentation from the \\file directive to the CameraManager class,\n> as it documents the class, not the file. Improve the documentation to\n> provide a brief overview of how the camera manager operates, and fix a\n> few typos and inconsistencies.\n>\n> The documentation mentions hotplug even though it isn't implement yet,\n> as this is a planned feature. More improvements are needed for the\n> documentation of the CameraManager member functions, and will be added\n> as part of the API improvements in the near future.\n>\n> Signed-off-by: Laurent Pinchart \n> ---\n> src/libcamera/camera_manager.cpp | 56 +++++++++++++++++++-------------\n> 1 file changed, 34 insertions(+), 22 deletions(-)\n>\n> diff --git a/src/libcamera/camera_manager.cpp b/src/libcamera/camera_manager.cpp\n> index e4072529fdc4..d91ca72a3802 100644\n> --- a/src/libcamera/camera_manager.cpp\n> +++ b/src/libcamera/camera_manager.cpp\n> @@ -15,30 +15,42 @@\n>\n> /**\n> * \\file camera_manager.h\n> - * \\brief Manage all cameras handled by libcamera\n> - *\n> - * The responsibility of the camera manager is to control the lifetime\n> - * management of objects provided by libcamera.\n> - *\n> - * When a user wish to interact with libcamera it creates and starts a\n> - * CameraManager object. Once confirmed the camera manager is running\n> - * the application can list all cameras detected by the library, get\n> - * one or more of the cameras and interact with them.\n> - *\n> - * When the user is done with the camera it should be returned to the\n> - * camera manager. Once all cameras are returned to the camera manager\n> - * the user is free to stop the manager.\n> - *\n> - * \\todo Add ability to add and remove media devices based on\n> - * hot-(un)plug events coming from the device enumerator.\n> - *\n> - * \\todo Add interface to register a notification callback to the user\n> - * to be able to inform it new cameras have been hot-plugged or\n> - * cameras have been removed due to hot-unplug.\n> + * \\brief The camera manager\n> */\n>\n> namespace libcamera {\n>\n> +/**\n> + * \\class CameraManager\n> + * \\brief Provide access and manage all cameras in the system\n> + *\n> + * The camera manager is the entry point to libcamera. Ii enumerates devices,\ns/Ii/It\n> + * associates them with pipeline managers, and provides access to the cameras\n> + * in the system to applications. The manager owns all Camera objects and\n> + * handles hot-plugging and hot-unplugging to manage the lifetime of cameras.\n> + *\n> + * To interact with libcamera, an application retrieves the camera manager\n> + * instance with CameraManager::instance(). The manager is initially stopped,\n> + * and shall be configured before being started. In particular a custom event\n> + * dispatcher shall be installed if needed with\n> + * CameraManager::setEventDispatcher().\n> + *\n> + * Once the camera manager is configured, it shall be started with start().\n> + * This will enumerate all the cameras present in the system, which can then be\n> + * listed with list() and retrieved with get().\n> + *\n> + * Cameras are reference-counted, and shall be returned to the camera manager\n> + * with Camera::put() after being used. Once all cameras have been returned to\n> + * the manager, it can be stopped with stop().\n> + *\n> + * \\todo Add ability to add and remove media devices based on hot-(un)plug\n> + * events coming from the device enumerator.\n> + *\n> + * \\todo Add interface to register a notification callback to the user to be\n> + * able to inform it new cameras have been hot-plugged or cameras have been\n> + * removed due to hot-unplug.\n> + */\n> +\n> CameraManager::CameraManager()\n> \t: enumerator_(nullptr), dispatcher_(nullptr)\n> {\n> @@ -57,7 +69,7 @@ CameraManager::~CameraManager()\n> * interact with cameras in the system until either the camera manager\n> * is stopped or the camera is unplugged from the system.\n> *\n> - * \\return true on successful start false otherwise\n> + * \\return 0 on successful start, or a negative error code otherwise\n\nAh, that was my comment on v1, please ignore it :)\n\n> */\n> int CameraManager::start()\n> {\n> @@ -100,7 +112,7 @@ int CameraManager::start()\n> /**\n> * \\brief Stop the camera manager\n> *\n> - * Before stopping the camera manger the caller is responsible for making\n> + * Before stopping the camera manager the caller is responsible for making\n> * sure all cameras provided by the manager are returned to the manager.\n> *\n> * After the manager has been stopped no resource provided by the camera\n\nReviewed-by: Jacopo Mondi \n\nThanks\n j\n\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 relay7-d.mail.gandi.net (relay7-d.mail.gandi.net\n\t[217.70.183.200])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 3D08360C68\n\tfor ;\n\tMon, 14 Jan 2019 10:38:08 +0100 (CET)","from uno.localdomain (2-224-242-101.ip172.fastwebnet.it\n\t[2.224.242.101]) (Authenticated sender: jacopo@jmondi.org)\n\tby relay7-d.mail.gandi.net (Postfix) with ESMTPSA id B72A92000E;\n\tMon, 14 Jan 2019 09:38:07 +0000 (UTC)"],"X-Originating-IP":"2.224.242.101","Date":"Mon, 14 Jan 2019 10:38:17 +0100","From":"Jacopo Mondi ","To":"Laurent Pinchart ","Cc":"libcamera-devel@lists.libcamera.org","Message-ID":"<20190114093817.7pwpgp3rwr4hzapn@uno.localdomain>","References":"<20190112144619.5816-1-laurent.pinchart@ideasonboard.com>\n\t<20190112144619.5816-3-laurent.pinchart@ideasonboard.com>","MIME-Version":"1.0","Content-Type":"multipart/signed; micalg=pgp-sha256;\n\tprotocol=\"application/pgp-signature\"; boundary=\"4hyijtptkznffcya\"","Content-Disposition":"inline","In-Reply-To":"<20190112144619.5816-3-laurent.pinchart@ideasonboard.com>","User-Agent":"NeoMutt/20180716","Subject":"Re: [libcamera-devel] [PATCH 2/3] libcamera: camera_manager:\n\tImprove class documentation","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":"Mon, 14 Jan 2019 09:38:08 -0000"}}]