Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1236525 > unrolled thread

[PATCH] staging: comedi: comedi_usb.c: improve function documentation

Back to article view | Back to linux.kernel

Contents

  [PATCH] staging: comedi: comedi_usb.c: improve function documentation Ian Abbott <abbotti@mev.co.uk> - 2015-09-30 18:40 +0200
    RE: [PATCH] staging: comedi: comedi_usb.c: improve function  documentation Hartley Sweeten <HartleyS@visionengravers.com> - 2015-09-30 20:40 +0200

#1236525 — [PATCH] staging: comedi: comedi_usb.c: improve function documentation

Expand the descriptions of the functions and document the return values.

Signed-off-by: Ian Abbott <abbotti@mev.co.uk>
---
 drivers/staging/comedi/comedi_usb.c | 75 +++++++++++++++++++++++++------------
 1 file changed, 52 insertions(+), 23 deletions(-)

diff --git a/drivers/staging/comedi/comedi_usb.c b/drivers/staging/comedi/comedi_usb.c
index 68b75e8..9c946d4 100644
--- a/drivers/staging/comedi/comedi_usb.c
+++ b/drivers/staging/comedi/comedi_usb.c
@@ -21,8 +21,14 @@
 #include "comedi_usb.h"
 
 /**
- * comedi_to_usb_interface() - comedi_device pointer to usb_interface pointer.
- * @dev: comedi_device struct
+ * comedi_to_usb_interface() - Return USB interface attached to COMEDI device
+ * @dev: COMEDI device.
+ *
+ * Assuming @dev->hw_dev is non-%NULL, it is assumed to be pointing to a
+ * a &struct device embedded in a &struct usb_interface.
+ *
+ * Return: Attached USB interface if @dev->hw_dev is non-%NULL.
+ * Return %NULL if @dev->hw_dev is %NULL.
  */
 struct usb_interface *comedi_to_usb_interface(struct comedi_device *dev)
 {
@@ -31,8 +37,14 @@ struct usb_interface *comedi_to_usb_interface(struct comedi_device *dev)
 EXPORT_SYMBOL_GPL(comedi_to_usb_interface);
 
 /**
- * comedi_to_usb_dev() - comedi_device pointer to usb_device pointer.
- * @dev: comedi_device struct
+ * comedi_to_usb_dev() - Return USB device attached to COMEDI device
+ * @dev: COMEDI device.
+ *
+ * Assuming @dev->hw_dev is non-%NULL, it is assumed to be pointing to a
+ * a &struct device embedded in a &struct usb_interface.
+ *
+ * Return: USB device to which the USB interface belongs if @dev->hw_dev is
+ * non-%NULL.  Return %NULL if @dev->hw_dev is %NULL.
  */
 struct usb_device *comedi_to_usb_dev(struct comedi_device *dev)
 {
@@ -43,12 +55,19 @@ struct usb_device *comedi_to_usb_dev(struct comedi_device *dev)
 EXPORT_SYMBOL_GPL(comedi_to_usb_dev);
 
 /**
- * comedi_usb_auto_config() - Configure/probe a comedi USB driver.
- * @intf: usb_interface struct
- * @driver: comedi_driver struct
- * @context: driver specific data, passed to comedi_auto_config()
+ * comedi_usb_auto_config() - Configure/probe a USB COMEDI driver
+ * @intf: USB interface.
+ * @driver: Registered COMEDI driver.
+ * @context: Driver specific data, passed to comedi_auto_config().
  *
- * Typically called from the usb_driver (*probe) function.
+ * Typically called from the usb_driver (*probe) function.  Auto-configure a
+ * COMEDI device, using a pointer to the &struct device embedded in *@intf as
+ * the hardware device.  The @context value gets passed through to @driver's
+ * "auto_attach" handler.  The "auto_attach" handler may call
+ * comedi_to_usb_interface() on the passed in COMEDI device to recover @intf.
+ *
+ * Return: The result of calling comedi_auto_config() (%0 on success, or
+ * a negative error number on failure).
  */
 int comedi_usb_auto_config(struct usb_interface *intf,
 			   struct comedi_driver *driver,
@@ -59,10 +78,18 @@ int comedi_usb_auto_config(struct usb_interface *intf,
 EXPORT_SYMBOL_GPL(comedi_usb_auto_config);
 
 /**
- * comedi_pci_auto_unconfig() - Unconfigure/disconnect a comedi USB driver.
- * @intf: usb_interface struct
+ * comedi_usb_auto_unconfig() - Unconfigure/disconnect a USB COMEDI device
+ * @intf: USB interface.
  *
  * Typically called from the usb_driver (*disconnect) function.
+ * Auto-unconfigure a COMEDI device attached to this USB interface, using a
+ * pointer to the &struct device embedded in *@intf as the hardware device.
+ * The COMEDI driver's "detach" handler will be called during unconfiguration
+ * of the COMEDI device.
+ *
+ * Note that the COMEDI device may have already been unconfigured using the
+ * %COMEDI_DEVCONFIG ioctl, in which case this attempt to unconfigure it
+ * again should be ignored.
  */
 void comedi_usb_auto_unconfig(struct usb_interface *intf)
 {
@@ -71,13 +98,15 @@ void comedi_usb_auto_unconfig(struct usb_interface *intf)
 EXPORT_SYMBOL_GPL(comedi_usb_auto_unconfig);
 
 /**
- * comedi_usb_driver_register() - Register a comedi USB driver.
- * @comedi_driver: comedi_driver struct
- * @usb_driver: usb_driver struct
+ * comedi_usb_driver_register() - Register a USB COMEDI driver
+ * @comedi_driver: COMEDI driver to be registered.
+ * @usb_driver: USB driver to be registered.
+ *
+ * This function is called from the module_init() of USB COMEDI driver modules
+ * to register the COMEDI driver and the USB driver.  Do not call it directly,
+ * use the module_comedi_usb_driver() helper macro instead.
  *
- * This function is used for the module_init() of comedi USB drivers.
- * Do not call it directly, use the module_comedi_usb_driver() helper
- * macro instead.
+ * Return: %0 on success, or a negative error number on failure.
  */
 int comedi_usb_driver_register(struct comedi_driver *comedi_driver,
 			       struct usb_driver *usb_driver)
@@ -99,13 +128,13 @@ int comedi_usb_driver_register(struct comedi_driver *comedi_driver,
 EXPORT_SYMBOL_GPL(comedi_usb_driver_register);
 
 /**
- * comedi_usb_driver_unregister() - Unregister a comedi USB driver.
- * @comedi_driver: comedi_driver struct
- * @usb_driver: usb_driver struct
+ * comedi_usb_driver_unregister() - Unregister a USB COMEDI driver
+ * @comedi_driver: COMEDI driver to be registered.
+ * @usb_driver: USB driver to be registered.
  *
- * This function is used for the module_exit() of comedi USB drivers.
- * Do not call it directly, use the module_comedi_usb_driver() helper
- * macro instead.
+ * This function is called from the module_exit() of USB COMEDI driver modules
+ * to unregister the USB driver and the COMEDI driver.  Do not call it
+ * directly, use the module_comedi_usb_driver() helper macro instead.
  */
 void comedi_usb_driver_unregister(struct comedi_driver *comedi_driver,
 				  struct usb_driver *usb_driver)
-- 
2.5.3

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[toc] | [next] | [standalone]

#1236640 — RE: [PATCH] staging: comedi: comedi_usb.c: improve function documentation

On Wednesday, September 30, 2015 9:37 AM, Ian Abbott wrote:
> Expand the descriptions of the functions and document the return values.
>
> Signed-off-by: Ian Abbott <abbotti@mev.co.uk>

Reviewed-by: H Hartley Sweeten <hsweeten@visionengravers.com>

--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/

[toc] | [prev] | [standalone]

Back to top | Article view | linux.kernel

csiph-web