[{"id":188,"web_url":"https://patchwork.libcamera.org/comment/188/","msgid":"<20190103103547.ovt2dpdfoub5kakb@uno.localdomain>","date":"2019-01-03T10:35:47","subject":"Re: [libcamera-devel] [PATCH 7/9] libcamera: device_enumerator:\n\tImprove documentation","submitter":{"id":3,"url":"https://patchwork.libcamera.org/api/people/3/","name":"Jacopo Mondi","email":"jacopo@jmondi.org"},"content":"Hi Laurent,\n\nOn Thu, Jan 03, 2019 at 03:31:08AM +0200, Laurent Pinchart wrote:\n> Miscellaneous documentation improvements for the DeviceEnumerator and\n> related classes.\n>\n> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>\n> ---\n>  src/libcamera/device_enumerator.cpp | 166 +++++++++++++++-------------\n>  1 file changed, 88 insertions(+), 78 deletions(-)\n>\n> diff --git a/src/libcamera/device_enumerator.cpp b/src/libcamera/device_enumerator.cpp\n> index a301420f39e1..81f6927b44e1 100644\n> --- a/src/libcamera/device_enumerator.cpp\n> +++ b/src/libcamera/device_enumerator.cpp\n> @@ -17,27 +17,25 @@\n>\n>  /**\n>   * \\file device_enumerator.h\n> - * \\brief Enumerating and matching of media devices\n> + * \\brief Enumeration and matching of media devices\n>   *\n> - * The purpose of device enumeration and matching is to find media\n> - * devices in the system and map one or more media devices to a pipeline\n> - * handler. During enumeration information about each media device is\n> - * gathered, transformed and stored.\n> + * The purpose of device enumeration and matching is to find media devices in\n> + * the system and map them to pipeline handlers.\n>   *\n> - * The core of the enumeration is DeviceEnumerator which is responsible\n> - * for all interactions with the operating system and the entry point\n> - * for other parts of libcamera.\n> + * At the code of the enumeration is the DeviceEnumerator class, responsible\n\ns/code/core/\n\nI have not find anything worth to point out in this series, that's not\nmy code and you should wait for Niklas' ack, but to me you could push\nthis whole series.\n\nReviewed-by: Jacopo Mondi <jacopo@jmondi.org>\n\nThanks\n  j\n\n> + * for enumerating all media devices in the system. It handles all interactions\n> + * with the operating system in a platform-specific way. For each media device\n> + * found an instance of MediaDevice is created to store information about the\n> + * device gathered from the kernel through the Media Controller API.\n>   *\n> - * The DeviceEnumerator can enumerate all or specific media devices in\n> - * the system. When a new media device is added the enumerator creates a\n> + * The DeviceEnumerator can enumerate all or specific media devices in the\n> + * system. When a new media device is added the enumerator creates a\n>   * corresponding MediaDevice instance.\n>   *\n> - * The last functionality provided is the ability to search among the\n> - * enumerate media devices for one matching information known to the\n> - * searcher. This is done by populating and passing a DeviceMatch object\n> - * to the DeviceEnumerator.\n> + * The enumerator supports searching among enumerated devices based on criteria\n> + * expressed in a DeviceMatch object.\n>   *\n> - * \\todo Add sysfs based device enumerator\n> + * \\todo Add sysfs based device enumerator.\n>   * \\todo Add support for hot-plug and hot-unplug.\n>   */\n>\n> @@ -47,18 +45,17 @@ namespace libcamera {\n>   * \\class DeviceMatch\n>   * \\brief Description of a media device search pattern\n>   *\n> - * The DeviceMatch class describes a media device using properties from\n> - * the v4l2 struct media_device_info, entity names in the media graph or\n> - * other properties which can be used to identify a media device.\n> + * The DeviceMatch class describes a media device using properties from the\n> + * Media Controller struct media_device_info, entity names in the media graph\n> + * or other properties that can be used to identify a media device.\n>   *\n> - * The description of a media device can then be passed to an enumerator\n> - * to try and find a matching media device.\n> + * The description is meant to be filled by pipeline managers and passed to a\n> + * device enumerator to find matching media devices.\n>   */\n>\n>  /**\n>   * \\brief Construct a media device search pattern\n> - *\n> - * \\param[in] driver The Linux device driver name who created the media device\n> + * \\param[in] driver The Linux device driver name that created the media device\n>   */\n>  DeviceMatch::DeviceMatch(const std::string &driver)\n>  \t: driver_(driver)\n> @@ -67,7 +64,6 @@ DeviceMatch::DeviceMatch(const std::string &driver)\n>\n>  /**\n>   * \\brief Add a media entity name to the search pattern\n> - *\n>   * \\param[in] entity The name of the entity in the media graph\n>   */\n>  void DeviceMatch::add(const std::string &entity)\n> @@ -79,8 +75,9 @@ void DeviceMatch::add(const std::string &entity)\n>   * \\brief Compare a search pattern with a media device\n>   * \\param[in] device The media device\n>   *\n> - * Matching is performed on the Linux device driver name and entity names\n> - * from the media graph.\n> + * Matching is performed on the Linux device driver name and entity names from\n> + * the media graph. A match is found if both the driver name matches and the\n> + * media device contains all the entities listed in the search pattern.\n>   *\n>   * \\return true if the media device matches the search pattern, false otherwise\n>   */\n> @@ -108,43 +105,44 @@ bool DeviceMatch::match(const MediaDevice *device) const\n>\n>  /**\n>   * \\class DeviceEnumerator\n> - * \\brief Enumerate, interrogate, store and search media device information\n> - *\n> - * The DeviceEnumerator class is responsible for all interactions with\n> - * the operation system when searching and interrogating media devices.\n> + * \\brief Enumerate, store and search media devices\n>   *\n> - * It is possible to automatically search and add all media devices in\n> - * the system or specify which media devices should be interrogated\n> - * in order for a specialized application to open as few resources\n> - * as possible to get hold of a specific camera.\n> - *\n> - * Once one or many media devices have been enumerated it is possible\n> - * to search among them to try and find a matching device using a\n> - * DeviceMatch object.\n> + * The DeviceEnumerator class is responsible for all interactions with the\n> + * operating system related to media devices. It enumerates all media devices\n> + * in the system, and for each device found creates an instance of the\n> + * MediaDevice class and stores it internally. The list of media devices can\n> + * then be searched using DeviceMatch search patterns.\n>   *\n> + * The enumerator also associates media device entities with device node paths.\n>   */\n>\n>  /**\n>   * \\brief Create a new device enumerator matching the systems capabilities\n>   *\n> - * Create a enumerator based on resource available to the system. Not all\n> - * different enumerator types are guaranteed to support all features.\n> + * Depending on how the operating system handles device detection, hot-plug\n> + * notification and device node lookup, different device enumerator\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>  DeviceEnumerator *DeviceEnumerator::create()\n>  {\n>  \tDeviceEnumerator *enumerator;\n>\n> -\t/* TODO: add compile time checks to only try udev enumerator if libudev is available */\n> +\t/**\n> +\t * \\todo Add compile time checks to only try udev enumerator if libudev\n> +\t * is available.\n> +\t */\n>  \tenumerator = new DeviceEnumeratorUdev();\n>  \tif (!enumerator->init())\n>  \t\treturn enumerator;\n>\n>  \t/*\n> -\t * NOTE: Either udev is not available or initialization of it\n> -\t * failed, use/fallback on sysfs enumerator\n> +\t * Either udev is not available or udev initialization failed. Fall back\n> +\t * on the sysfs enumerator.\n>  \t */\n>\n> -\t/* TODO: add a sysfs based enumerator */\n> +\t/** \\todo Add a sysfs-based enumerator. */\n>\n>  \treturn nullptr;\n>  }\n> @@ -160,13 +158,38 @@ DeviceEnumerator::~DeviceEnumerator()\n>  }\n>\n>  /**\n> - * \\brief Add a media device to the enumerator\n> + * \\fn DeviceEnumerator::init()\n> + * \\brief Initialize the enumerator\n> + * \\return 0 on success, or a negative error code otherwise\n> + * \\retval -EBUSY the enumerator has already been initialized\n> + * \\retval -ENODEV the enumerator can't enumerate devices\n> + */\n> +\n> +/**\n> + * \\fn DeviceEnumerator::enumerate()\n> + * \\brief Enumerate all media devices in the system\n> + *\n> + * This function finds and add all media devices in the system to the\n> + * enumerator. It shall be implemented by all subclasses of DeviceEnumerator\n> + * using system-specific methods.\n> + *\n> + * Individual media devices that can't be properly enumerated shall be skipped\n> + * with a warning message logged, without returning an error. Only errors that\n> + * prevent enumeration altogether shall be fatal.\n>   *\n> + * \\return 0 on success, or a negative error code on fatal errors.\n> + */\n> +\n> +/**\n> + * \\brief Add a media device to the enumerator\n>   * \\param[in] devnode path to the media device to add\n>   *\n> - * Opens the media device and quires its topology and other information.\n> + * Create a media device for the \\a devnode, open it, populate its media graph,\n> + * and look up device nodes associated with all entities. Store the media device\n> + * in the internal list for later matching with pipeline handlers.\n>   *\n> - * \\return 0 on success none zero otherwise\n> + * \\return 0 on success, or a negative error code if the media device can't be\n> + * created or populated\n>   */\n>  int DeviceEnumerator::addDevice(const std::string &devnode)\n>  {\n> @@ -205,15 +228,14 @@ int DeviceEnumerator::addDevice(const std::string &devnode)\n>\n>  /**\n>   * \\brief Search available media devices for a pattern match\n> - *\n>   * \\param[in] dm Search pattern\n>   *\n> - * Search in the enumerated media devices that are not already in use\n> - * for a match described in \\a dm. If a match is found and the caller\n> - * intends to use it the caller is responsible to mark the MediaDevice\n> - * object as in use and to release it when it's done with it.\n> + * Search in the enumerated media devices that are not already in use for a\n> + * match described in \\a dm. If a match is found and the caller intends to use\n> + * it the caller is responsible for acquiring the MediaDevice object and\n> + * releasing it when done with it.\n>   *\n> - * \\return pointer to the matching MediaDevice, nullptr if no match is found\n> + * \\return pointer to the matching MediaDevice, or nullptr if no match is found\n>   */\n>  MediaDevice *DeviceEnumerator::search(const DeviceMatch &dm) const\n>  {\n> @@ -229,10 +251,21 @@ MediaDevice *DeviceEnumerator::search(const DeviceMatch &dm) const\n>  }\n>\n>  /**\n> - * \\class DeviceEnumeratorUdev\n> - * \\brief Udev implementation of device enumeration\n> + * \\fn DeviceEnumerator::lookupDevnode(int major, int minor)\n> + * \\brief Lookup device node path from device number\n> + * \\param major The device major number\n> + * \\param minor The device minor number\n>   *\n> - * Implementation of system enumeration functions using libudev.\n> + * Translate a device number given as \\a major and \\a minor to a device node\n> + * path.\n> + *\n> + * \\return the device node path on success, or an empty string if the lookup\n> + * fails\n> + */\n> +\n> +/**\n> + * \\class DeviceEnumeratorUdev\n> + * \\brief Device enumerator based on libudev\n>   */\n>\n>  DeviceEnumeratorUdev::DeviceEnumeratorUdev()\n> @@ -246,13 +279,6 @@ DeviceEnumeratorUdev::~DeviceEnumeratorUdev()\n>  \t\tudev_unref(udev_);\n>  }\n>\n> -/**\n> - * \\brief Initialize the enumerator\n> - *\n> - * \\retval 0 Initialized\n> - * \\retval -EBUSY Busy (already initialized)\n> - * \\retval -ENODEV Failed to talk to udev\n> - */\n>  int DeviceEnumeratorUdev::init()\n>  {\n>  \tif (udev_)\n> @@ -265,14 +291,6 @@ int DeviceEnumeratorUdev::init()\n>  \treturn 0;\n>  }\n>\n> -/**\n> - * \\brief Enumerate all media devices using udev\n> - *\n> - * Find, enumerate and add all media devices in the system to the\n> - * enumerator.\n> - *\n> - * \\return 0 on success none zero otherwise\n> - */\n>  int DeviceEnumeratorUdev::enumerate()\n>  {\n>  \tstruct udev_enumerate *udev_enum = nullptr;\n> @@ -323,14 +341,6 @@ done:\n>  \treturn ret >= 0 ? 0 : ret;\n>  }\n>\n> -/**\n> - * \\brief Lookup device node from device number using udev\n> - *\n> - * Translate a device number (major, minor) to a device node path.\n> - *\n> - * \\return device node path or empty string if lookup fails.\n> - *\n> - */\n>  std::string DeviceEnumeratorUdev::lookupDevnode(int major, int minor)\n>  {\n>  \tstruct udev_device *device;\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":"<jacopo@jmondi.org>","Received":["from relay9-d.mail.gandi.net (relay9-d.mail.gandi.net\n\t[217.70.183.199])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id 9D30960B0B\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tThu,  3 Jan 2019 11:35:44 +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 relay9-d.mail.gandi.net (Postfix) with ESMTPSA id 29AADFF80D;\n\tThu,  3 Jan 2019 10:35:43 +0000 (UTC)"],"X-Originating-IP":"2.224.242.101","Date":"Thu, 3 Jan 2019 11:35:47 +0100","From":"Jacopo Mondi <jacopo@jmondi.org>","To":"Laurent Pinchart <laurent.pinchart@ideasonboard.com>","Cc":"libcamera-devel@lists.libcamera.org","Message-ID":"<20190103103547.ovt2dpdfoub5kakb@uno.localdomain>","References":"<20190103013110.6849-1-laurent.pinchart@ideasonboard.com>\n\t<20190103013110.6849-7-laurent.pinchart@ideasonboard.com>","MIME-Version":"1.0","Content-Type":"multipart/signed; micalg=pgp-sha256;\n\tprotocol=\"application/pgp-signature\"; boundary=\"gyz272b5rdmjcm7j\"","Content-Disposition":"inline","In-Reply-To":"<20190103013110.6849-7-laurent.pinchart@ideasonboard.com>","User-Agent":"NeoMutt/20180716","Subject":"Re: [libcamera-devel] [PATCH 7/9] libcamera: device_enumerator:\n\tImprove documentation","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":"Thu, 03 Jan 2019 10:35:44 -0000"}},{"id":197,"web_url":"https://patchwork.libcamera.org/comment/197/","msgid":"<20190103213419.GI22790@bigcity.dyn.berto.se>","date":"2019-01-03T21:34:19","subject":"Re: [libcamera-devel] [PATCH 7/9] libcamera: device_enumerator:\n\tImprove documentation","submitter":{"id":5,"url":"https://patchwork.libcamera.org/api/people/5/","name":"Niklas Söderlund","email":"niklas.soderlund@ragnatech.se"},"content":"Hi Laurent,\n\nA big thanks for improving my initial documentation. This changes makes \nit much more understandable.\n\nOn 2019-01-03 03:31:08 +0200, Laurent Pinchart wrote:\n> Miscellaneous documentation improvements for the DeviceEnumerator and\n> related classes.\n> \n> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>\n\nApart from the issue pointed out by Jacopo,\n\nReviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>\n\n> ---\n>  src/libcamera/device_enumerator.cpp | 166 +++++++++++++++-------------\n>  1 file changed, 88 insertions(+), 78 deletions(-)\n> \n> diff --git a/src/libcamera/device_enumerator.cpp b/src/libcamera/device_enumerator.cpp\n> index a301420f39e1..81f6927b44e1 100644\n> --- a/src/libcamera/device_enumerator.cpp\n> +++ b/src/libcamera/device_enumerator.cpp\n> @@ -17,27 +17,25 @@\n>  \n>  /**\n>   * \\file device_enumerator.h\n> - * \\brief Enumerating and matching of media devices\n> + * \\brief Enumeration and matching of media devices\n>   *\n> - * The purpose of device enumeration and matching is to find media\n> - * devices in the system and map one or more media devices to a pipeline\n> - * handler. During enumeration information about each media device is\n> - * gathered, transformed and stored.\n> + * The purpose of device enumeration and matching is to find media devices in\n> + * the system and map them to pipeline handlers.\n>   *\n> - * The core of the enumeration is DeviceEnumerator which is responsible\n> - * for all interactions with the operating system and the entry point\n> - * for other parts of libcamera.\n> + * At the code of the enumeration is the DeviceEnumerator class, responsible\n> + * for enumerating all media devices in the system. It handles all interactions\n> + * with the operating system in a platform-specific way. For each media device\n> + * found an instance of MediaDevice is created to store information about the\n> + * device gathered from the kernel through the Media Controller API.\n>   *\n> - * The DeviceEnumerator can enumerate all or specific media devices in\n> - * the system. When a new media device is added the enumerator creates a\n> + * The DeviceEnumerator can enumerate all or specific media devices in the\n> + * system. When a new media device is added the enumerator creates a\n>   * corresponding MediaDevice instance.\n>   *\n> - * The last functionality provided is the ability to search among the\n> - * enumerate media devices for one matching information known to the\n> - * searcher. This is done by populating and passing a DeviceMatch object\n> - * to the DeviceEnumerator.\n> + * The enumerator supports searching among enumerated devices based on criteria\n> + * expressed in a DeviceMatch object.\n>   *\n> - * \\todo Add sysfs based device enumerator\n> + * \\todo Add sysfs based device enumerator.\n>   * \\todo Add support for hot-plug and hot-unplug.\n>   */\n>  \n> @@ -47,18 +45,17 @@ namespace libcamera {\n>   * \\class DeviceMatch\n>   * \\brief Description of a media device search pattern\n>   *\n> - * The DeviceMatch class describes a media device using properties from\n> - * the v4l2 struct media_device_info, entity names in the media graph or\n> - * other properties which can be used to identify a media device.\n> + * The DeviceMatch class describes a media device using properties from the\n> + * Media Controller struct media_device_info, entity names in the media graph\n> + * or other properties that can be used to identify a media device.\n>   *\n> - * The description of a media device can then be passed to an enumerator\n> - * to try and find a matching media device.\n> + * The description is meant to be filled by pipeline managers and passed to a\n> + * device enumerator to find matching media devices.\n>   */\n>  \n>  /**\n>   * \\brief Construct a media device search pattern\n> - *\n> - * \\param[in] driver The Linux device driver name who created the media device\n> + * \\param[in] driver The Linux device driver name that created the media device\n>   */\n>  DeviceMatch::DeviceMatch(const std::string &driver)\n>  \t: driver_(driver)\n> @@ -67,7 +64,6 @@ DeviceMatch::DeviceMatch(const std::string &driver)\n>  \n>  /**\n>   * \\brief Add a media entity name to the search pattern\n> - *\n>   * \\param[in] entity The name of the entity in the media graph\n>   */\n>  void DeviceMatch::add(const std::string &entity)\n> @@ -79,8 +75,9 @@ void DeviceMatch::add(const std::string &entity)\n>   * \\brief Compare a search pattern with a media device\n>   * \\param[in] device The media device\n>   *\n> - * Matching is performed on the Linux device driver name and entity names\n> - * from the media graph.\n> + * Matching is performed on the Linux device driver name and entity names from\n> + * the media graph. A match is found if both the driver name matches and the\n> + * media device contains all the entities listed in the search pattern.\n>   *\n>   * \\return true if the media device matches the search pattern, false otherwise\n>   */\n> @@ -108,43 +105,44 @@ bool DeviceMatch::match(const MediaDevice *device) const\n>  \n>  /**\n>   * \\class DeviceEnumerator\n> - * \\brief Enumerate, interrogate, store and search media device information\n> - *\n> - * The DeviceEnumerator class is responsible for all interactions with\n> - * the operation system when searching and interrogating media devices.\n> + * \\brief Enumerate, store and search media devices\n>   *\n> - * It is possible to automatically search and add all media devices in\n> - * the system or specify which media devices should be interrogated\n> - * in order for a specialized application to open as few resources\n> - * as possible to get hold of a specific camera.\n> - *\n> - * Once one or many media devices have been enumerated it is possible\n> - * to search among them to try and find a matching device using a\n> - * DeviceMatch object.\n> + * The DeviceEnumerator class is responsible for all interactions with the\n> + * operating system related to media devices. It enumerates all media devices\n> + * in the system, and for each device found creates an instance of the\n> + * MediaDevice class and stores it internally. The list of media devices can\n> + * then be searched using DeviceMatch search patterns.\n>   *\n> + * The enumerator also associates media device entities with device node paths.\n>   */\n>  \n>  /**\n>   * \\brief Create a new device enumerator matching the systems capabilities\n>   *\n> - * Create a enumerator based on resource available to the system. Not all\n> - * different enumerator types are guaranteed to support all features.\n> + * Depending on how the operating system handles device detection, hot-plug\n> + * notification and device node lookup, different device enumerator\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>  DeviceEnumerator *DeviceEnumerator::create()\n>  {\n>  \tDeviceEnumerator *enumerator;\n>  \n> -\t/* TODO: add compile time checks to only try udev enumerator if libudev is available */\n> +\t/**\n> +\t * \\todo Add compile time checks to only try udev enumerator if libudev\n> +\t * is available.\n> +\t */\n>  \tenumerator = new DeviceEnumeratorUdev();\n>  \tif (!enumerator->init())\n>  \t\treturn enumerator;\n>  \n>  \t/*\n> -\t * NOTE: Either udev is not available or initialization of it\n> -\t * failed, use/fallback on sysfs enumerator\n> +\t * Either udev is not available or udev initialization failed. Fall back\n> +\t * on the sysfs enumerator.\n>  \t */\n>  \n> -\t/* TODO: add a sysfs based enumerator */\n> +\t/** \\todo Add a sysfs-based enumerator. */\n>  \n>  \treturn nullptr;\n>  }\n> @@ -160,13 +158,38 @@ DeviceEnumerator::~DeviceEnumerator()\n>  }\n>  \n>  /**\n> - * \\brief Add a media device to the enumerator\n> + * \\fn DeviceEnumerator::init()\n> + * \\brief Initialize the enumerator\n> + * \\return 0 on success, or a negative error code otherwise\n> + * \\retval -EBUSY the enumerator has already been initialized\n> + * \\retval -ENODEV the enumerator can't enumerate devices\n> + */\n> +\n> +/**\n> + * \\fn DeviceEnumerator::enumerate()\n> + * \\brief Enumerate all media devices in the system\n> + *\n> + * This function finds and add all media devices in the system to the\n> + * enumerator. It shall be implemented by all subclasses of DeviceEnumerator\n> + * using system-specific methods.\n> + *\n> + * Individual media devices that can't be properly enumerated shall be skipped\n> + * with a warning message logged, without returning an error. Only errors that\n> + * prevent enumeration altogether shall be fatal.\n>   *\n> + * \\return 0 on success, or a negative error code on fatal errors.\n> + */\n> +\n> +/**\n> + * \\brief Add a media device to the enumerator\n>   * \\param[in] devnode path to the media device to add\n>   *\n> - * Opens the media device and quires its topology and other information.\n> + * Create a media device for the \\a devnode, open it, populate its media graph,\n> + * and look up device nodes associated with all entities. Store the media device\n> + * in the internal list for later matching with pipeline handlers.\n>   *\n> - * \\return 0 on success none zero otherwise\n> + * \\return 0 on success, or a negative error code if the media device can't be\n> + * created or populated\n>   */\n>  int DeviceEnumerator::addDevice(const std::string &devnode)\n>  {\n> @@ -205,15 +228,14 @@ int DeviceEnumerator::addDevice(const std::string &devnode)\n>  \n>  /**\n>   * \\brief Search available media devices for a pattern match\n> - *\n>   * \\param[in] dm Search pattern\n>   *\n> - * Search in the enumerated media devices that are not already in use\n> - * for a match described in \\a dm. If a match is found and the caller\n> - * intends to use it the caller is responsible to mark the MediaDevice\n> - * object as in use and to release it when it's done with it.\n> + * Search in the enumerated media devices that are not already in use for a\n> + * match described in \\a dm. If a match is found and the caller intends to use\n> + * it the caller is responsible for acquiring the MediaDevice object and\n> + * releasing it when done with it.\n>   *\n> - * \\return pointer to the matching MediaDevice, nullptr if no match is found\n> + * \\return pointer to the matching MediaDevice, or nullptr if no match is found\n>   */\n>  MediaDevice *DeviceEnumerator::search(const DeviceMatch &dm) const\n>  {\n> @@ -229,10 +251,21 @@ MediaDevice *DeviceEnumerator::search(const DeviceMatch &dm) const\n>  }\n>  \n>  /**\n> - * \\class DeviceEnumeratorUdev\n> - * \\brief Udev implementation of device enumeration\n> + * \\fn DeviceEnumerator::lookupDevnode(int major, int minor)\n> + * \\brief Lookup device node path from device number\n> + * \\param major The device major number\n> + * \\param minor The device minor number\n>   *\n> - * Implementation of system enumeration functions using libudev.\n> + * Translate a device number given as \\a major and \\a minor to a device node\n> + * path.\n> + *\n> + * \\return the device node path on success, or an empty string if the lookup\n> + * fails\n> + */\n> +\n> +/**\n> + * \\class DeviceEnumeratorUdev\n> + * \\brief Device enumerator based on libudev\n>   */\n>  \n>  DeviceEnumeratorUdev::DeviceEnumeratorUdev()\n> @@ -246,13 +279,6 @@ DeviceEnumeratorUdev::~DeviceEnumeratorUdev()\n>  \t\tudev_unref(udev_);\n>  }\n>  \n> -/**\n> - * \\brief Initialize the enumerator\n> - *\n> - * \\retval 0 Initialized\n> - * \\retval -EBUSY Busy (already initialized)\n> - * \\retval -ENODEV Failed to talk to udev\n> - */\n>  int DeviceEnumeratorUdev::init()\n>  {\n>  \tif (udev_)\n> @@ -265,14 +291,6 @@ int DeviceEnumeratorUdev::init()\n>  \treturn 0;\n>  }\n>  \n> -/**\n> - * \\brief Enumerate all media devices using udev\n> - *\n> - * Find, enumerate and add all media devices in the system to the\n> - * enumerator.\n> - *\n> - * \\return 0 on success none zero otherwise\n> - */\n>  int DeviceEnumeratorUdev::enumerate()\n>  {\n>  \tstruct udev_enumerate *udev_enum = nullptr;\n> @@ -323,14 +341,6 @@ done:\n>  \treturn ret >= 0 ? 0 : ret;\n>  }\n>  \n> -/**\n> - * \\brief Lookup device node from device number using udev\n> - *\n> - * Translate a device number (major, minor) to a device node path.\n> - *\n> - * \\return device node path or empty string if lookup fails.\n> - *\n> - */\n>  std::string DeviceEnumeratorUdev::lookupDevnode(int major, int minor)\n>  {\n>  \tstruct udev_device *device;\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":"<niklas.soderlund@ragnatech.se>","Received":["from mail-lj1-x241.google.com (mail-lj1-x241.google.com\n\t[IPv6:2a00:1450:4864:20::241])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id B443160B21\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tThu,  3 Jan 2019 22:34:21 +0100 (CET)","by mail-lj1-x241.google.com with SMTP id l15-v6so30875558lja.9\n\tfor <libcamera-devel@lists.libcamera.org>;\n\tThu, 03 Jan 2019 13:34:21 -0800 (PST)","from localhost (89-233-230-99.cust.bredband2.com. [89.233.230.99])\n\tby smtp.gmail.com with ESMTPSA id\n\tt18sm10732031lft.93.2019.01.03.13.34.19\n\t(version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256);\n\tThu, 03 Jan 2019 13:34:20 -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=oI1RNBmffRahpqFWqLwAJ4yc5Vo3nOZrEfle6YW6MM8=;\n\tb=W9o60FzjcYP6o4Gw57vxhZPlNkvZ3aGVDiEFd3ttPwd56z+U6oSfi6lawqCXL1oP7k\n\tkMrLeuUQkjDljWuftuchKBi/isQ5po6WrKuJfQDsrbhnb/cdRQAb2OgMCDMSnjuAwVWe\n\txYbxA2dh0ou1GGGuR26edzwaRXLKC676uF3wL4wDHKJBCxem0kfNwjCUdP45DCt+Bbod\n\t4HJ0oDZtS/xmstN2Ix8Rq+XY9F3uwW0pN2Up262cYTpF8Ovt4bVaW0YrYD2Y6n7HgLge\n\tOxcb1pEqpSDfQNtiQ5uj/63h89DCmyXu64C30VzVnn3mANICgAS3jRivYceceOO3eHOs\n\tsUmw==","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=oI1RNBmffRahpqFWqLwAJ4yc5Vo3nOZrEfle6YW6MM8=;\n\tb=hyd4kV/XGHBZMzFKRWgvkRJLe5ylWmLQgHMdy0ZH1d0I4cXzNjLA0k0cEw7PPqSdWh\n\t7PZs6nbz7fCQKqx43KGygB84wdj7gVjhFHO8UJflJ6S06WRNDlrcmzvSk26yVwUh/scA\n\tjgbTI0R091WxzbC1wi7MbphjEorqMHdbFJSpldMRWZajlbCb7Al0Z6DBvPTljqMwVWTa\n\tUaviblptSzB1D2LRoX3B+qNOLDjD+mI7eHXxJvzBp3xZtefydtA6d8Dfx+5Hr4ESXOdn\n\tcGi3NGtil3Uu4RHa2GvF/ibAenSDpLsrqPhezmUq4knoIkNpwT7BwtWbldKpmhyEul5R\n\tYWoQ==","X-Gm-Message-State":"AJcUukdBuYr54FvyxeMUl0tBI0OfuaiRrnZ6OJKmIvZNgT7JeLUUodBO\n\t59ftFchXuj2FQqhv398joXjpVA==","X-Google-Smtp-Source":"ALg8bN73RKAF8nIQpRSCyx7RC3MluqpDbyg01ZNEPtO7NMIqvQSRHMVqaghRjMNqKkksYhB8AzhxOg==","X-Received":"by 2002:a2e:1552:: with SMTP id\n\t18-v6mr2305831ljv.68.1546551260875; \n\tThu, 03 Jan 2019 13:34:20 -0800 (PST)","Date":"Thu, 3 Jan 2019 22:34:19 +0100","From":"Niklas =?iso-8859-1?q?S=F6derlund?= <niklas.soderlund@ragnatech.se>","To":"Laurent Pinchart <laurent.pinchart@ideasonboard.com>","Cc":"libcamera-devel@lists.libcamera.org","Message-ID":"<20190103213419.GI22790@bigcity.dyn.berto.se>","References":"<20190103013110.6849-1-laurent.pinchart@ideasonboard.com>\n\t<20190103013110.6849-7-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":"<20190103013110.6849-7-laurent.pinchart@ideasonboard.com>","User-Agent":"Mutt/1.10.1 (2018-07-13)","Subject":"Re: [libcamera-devel] [PATCH 7/9] libcamera: device_enumerator:\n\tImprove documentation","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":"Thu, 03 Jan 2019 21:34:22 -0000"}}]