diff options
author | Ian Abbott <abbotti@mev.co.uk> | 2015-09-30 16:37:13 (GMT) |
---|---|---|
committer | Greg Kroah-Hartman <gregkh@linuxfoundation.org> | 2015-10-02 09:43:21 (GMT) |
commit | ddf837ea95017a658d2a4bac6b89fc0989f2e5e6 (patch) | |
tree | 11df727a244af511e89f8bd6bd9c85bc3d2096b6 /drivers/staging/comedi/comedi_usb.c | |
parent | 127a0cf9b091fe85b6624a4ac8164d6b2cf76143 (diff) | |
download | linux-ddf837ea95017a658d2a4bac6b89fc0989f2e5e6.tar.xz |
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>
Reviewed-by: H Hartley Sweeten <hsweeten@visionengravers.com>
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Diffstat (limited to 'drivers/staging/comedi/comedi_usb.c')
-rw-r--r-- | drivers/staging/comedi/comedi_usb.c | 75 |
1 files 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) |