[PATCH] USB: <linux/usb_gadget.h> minor doc updates

Small kerneldoc clarifications:

  - more endpoint halt clearing info:
      * some hardware can't do it; which causes problems with drivers
        that want to use multiple interfaces or altsettings.
      * it doesn't affect queuing of data (should help usb-storage
        gadget driver, plus it's more sensible this way);
  - disconnect() callback not guaranteed: some hardware can't tell

Mostly this captures answers to questions I've been asked.

include/linux/usb_gadget.h

@@ -313,8 +313,8 @@ usb_ep_free_buffer (struct usb_ep *ep, void *buf, dma_addr_t dma, unsigned len)
  * arranges to poll once per interval, and the gadget driver usually will
  * have queued some data to transfer at that time.
  *
- * Returns zero, or a negative error code.  Endpoints that are not enabled,
- * or which are enabled but halted, report errors; errors will also be
+ * Returns zero, or a negative error code.  Endpoints that are not enabled
+ * report errors; errors will also be
  * reported when the usb peripheral is disconnected.
  */
 static inline int
@@ -352,6 +352,11 @@ static inline int usb_ep_dequeue (struct usb_ep *ep, struct usb_request *req)
  * clears this feature; drivers may need to empty the endpoint's request
  * queue first, to make sure no inappropriate transfers happen.
  *
+ * Note that while an endpoint CLEAR_FEATURE will be invisible to the
+ * gadget driver, a SET_INTERFACE will not be.  To reset endpoints for the
+ * current altsetting, see usb_ep_clear_halt().  When switching altsettings,
+ * it's simplest to use usb_ep_enable() or usb_ep_disable() for the endpoints.
+ *
  * Returns zero, or a negative error code.  On success, this call sets
  * underlying hardware state that blocks data transfers.
  */
@@ -365,12 +370,14 @@ usb_ep_set_halt (struct usb_ep *ep)
  * usb_ep_clear_halt - clears endpoint halt, and resets toggle
  * @ep:the bulk or interrupt endpoint being reset
  *
- * use this when responding to the standard usb "set interface" request,
+ * Use this when responding to the standard usb "set interface" request,
  * for endpoints that aren't reconfigured, after clearing any other state
  * in the endpoint's i/o queue.
  *
- * returns zero, or a negative error code.  on success, this call clears
+ * Returns zero, or a negative error code.  On success, this call clears
  * the underlying hardware state reflecting endpoint halt and data toggle.
+ * Note that some hardware can't support this request (like pxa2xx_udc),
+ * and accordingly can't correctly implement interface altsettings.
  */
 static inline int
 usb_ep_clear_halt (struct usb_ep *ep)
@@ -562,7 +569,8 @@ usb_gadget_clear_selfpowered (struct usb_gadget *gadget)
  *	queues a response to ep0, or returns negative to stall.
  * @disconnect: Invoked after all transfers have been stopped,
  * 	when the host is disconnected.  May be called in_interrupt; this
- * 	may not sleep.
+ * 	may not sleep.  Some devices can't detect disconnect, so this might
+ *	not be called except as part of controller shutdown.
  * @unbind: Invoked when the driver is unbound from a gadget,
  * 	usually from rmmod (after a disconnect is reported).
  * 	Called in a context that permits sleeping.
@@ -603,7 +611,9 @@ usb_gadget_clear_selfpowered (struct usb_gadget *gadget)
  * not provide those callbacks.  However, some may need to change modes
  * when the host is not longer directing those activities.  For example,
  * local controls (buttons, dials, etc) may need to be re-enabled since
- * the (remote) host can't do that any longer. 
+ * the (remote) host can't do that any longer; or an error state might
+ * be cleared, to make the device behave identically whether or not
+ * power is maintained.
  */
 struct usb_gadget_driver {
 	char			*function;