Commit ddf837ea authored by Ian Abbott's avatar Ian Abbott Committed by Greg Kroah-Hartman
Browse files

staging: comedi: comedi_usb.c: improve function documentation 



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

Signed-off-by: default avatarIan Abbott <abbotti@mev.co.uk>
Reviewed-by: default avatarH Hartley Sweeten <hsweeten@visionengravers.com>
Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent 127a0cf9

drivers/staging/comedi/comedi_usb.c

+52 −23
Original line number Diff line number Diff line
@@ -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)