From: Ian Abbott Date: Wed, 30 Sep 2015 16:37:13 +0000 (+0100) Subject: staging: comedi: comedi_usb.c: improve function documentation X-Git-Tag: firefly_0821_release~176^2~802^2~1312 X-Git-Url: http://demsky.eecs.uci.edu/git/?a=commitdiff_plain;h=ddf837ea95017a658d2a4bac6b89fc0989f2e5e6;p=firefly-linux-kernel-4.4.55.git staging: comedi: comedi_usb.c: improve function documentation Expand the descriptions of the functions and document the return values. Signed-off-by: Ian Abbott Reviewed-by: H Hartley Sweeten Signed-off-by: Greg Kroah-Hartman --- diff --git a/drivers/staging/comedi/comedi_usb.c b/drivers/staging/comedi/comedi_usb.c index 68b75e8feec0..9c946d40b894 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)