Changeset 3b77628 in mainline

Timestamp:

2011-01-24T11:58:24Z (13 years ago)

Author:

Vojtech Horky <vojtechhorky@…>

Branches:

lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export

Children:

afc4fbb

Parents:

0cfc68f0

Message:

Doxygen comment fixes

Mainly proper subgrouping and some missing @param comments.

Location:

uspace

Files:

• doc/doxygroups.h (modified) (1 diff)
• drv/usbhub/usbhub.c (modified) (1 diff)
• drv/usbhub/usblist.c (modified) (1 diff)
• drv/usbhub/usblist.h (modified) (3 diffs)
• drv/usbhub/utils.c (modified) (1 diff)
• drv/vhc/devices.c (modified) (2 diffs)
• lib/drv/include/usb_iface.h (modified) (1 diff)
• lib/drv/include/usbhc_iface.h (modified) (1 diff)
• lib/usb/include/usb/classes/classes.h (modified) (1 diff)
• lib/usb/include/usb/classes/hid.h (modified) (1 diff)
• lib/usb/include/usb/classes/hidparser.h (modified) (1 diff)
• lib/usb/include/usb/classes/hidut.h (modified) (1 diff)
• lib/usb/include/usb/classes/hidutkbd.h (modified) (1 diff)
• lib/usb/include/usb/classes/hub.h (modified) (2 diffs)
• lib/usb/include/usb/debug.h (modified) (2 diffs)
• lib/usb/include/usb/descriptor.h (modified) (1 diff)
• lib/usb/include/usb/devreq.h (modified) (1 diff)
• lib/usb/include/usb/hcd.h (modified) (2 diffs)
• lib/usb/include/usb/hcdhubd.h (modified) (1 diff)
• lib/usb/include/usb/usb.h (modified) (1 diff)
• lib/usb/include/usb/usbdrv.h (modified) (1 diff)
• lib/usb/src/addrkeep.c (modified) (1 diff)
• lib/usb/src/class.c (modified) (1 diff)
• lib/usb/src/debug.c (modified) (1 diff)
• lib/usb/src/dp.c (modified) (1 diff)
• lib/usb/src/drvpsync.c (modified) (1 diff)
• lib/usb/src/hcdhubd.c (modified) (1 diff)
• lib/usb/src/hcdhubd_private.h (modified) (1 diff)
• lib/usb/src/hcdrv.c (modified) (1 diff)
• lib/usb/src/hidparser.c (modified) (1 diff)
• lib/usb/src/localdrv.c (modified) (1 diff)
• lib/usb/src/recognise.c (modified) (4 diffs)
• lib/usb/src/remotedrv.c (modified) (1 diff)
• lib/usb/src/usb.c (modified) (1 diff)
• lib/usb/src/usbdrv.c (modified) (1 diff)
• lib/usb/src/usbdrvreq.c (modified) (2 diffs)
• lib/usbvirt/src/main.c (modified) (1 diff)

uspace/doc/doxygroups.h

@@ -176 +176 @@
          * @brief Library for creating USB devices drivers.
          */
+
+         /**
+          * @defgroup usbhub USB hub driver
+          * @ingroup usb
+          * @brief USB hub driver.
+          */
+          */
+

uspace/drv/usbhub/usbhub.c

@@ -26 +26 @@
  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
-/** @addtogroup usb hub driver
+/** @addtogroup usbhub
  * @{
  */

uspace/drv/usbhub/usblist.c

@@ -26 +26 @@
  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
-/** @addtogroup usb hub driver
+/** @addtogroup usbhub
  * @{
  */

uspace/drv/usbhub/usblist.h

@@ -27 +27 @@
  */
 
-
-#ifndef USBLIST_H
-#define USBLIST_H
-/** @addtogroup usb hub driver
+/** @addtogroup usbhub
  * @{
  */
@@ -40 +37 @@
  * much simpler and more straight-forward semantics.
  */
+#ifndef USBLIST_H
+#define USBLIST_H
 
 /**
@@ -78 +77 @@
 }
 
-
+#endif  /* USBLIST_H */
 /**
  * @}
  */
-
-
-
-#endif  /* USBLIST_H */
-

uspace/drv/usbhub/utils.c

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup usbhub
  * @{
  */

uspace/drv/vhc/devices.c

@@ -58 +58 @@
 /** Create virtual device.
  *
- * @param address USB address.
  * @param phone Callback phone.
  * @return New device.
- * @retval NULL Out of memory or address already occupied.
+ * @retval NULL Out of memory.
  */
 virtdev_connection_t *virtdev_add_device(int phone)
@@ -67 +66 @@
         virtdev_connection_t *dev = (virtdev_connection_t *)
             malloc(sizeof(virtdev_connection_t));
+        if (dev == NULL) {
+                return NULL;
+        }
+
         dev->phone = phone;
         list_append(&dev->link, &devices);

uspace/lib/drv/include/usb_iface.h

@@ -27 +27 @@
  */
 
-/** @addtogroup libdrv usb
+/** @addtogroup libdrv
+ * @addtogroup usb
  * @{
  */

uspace/lib/drv/include/usbhc_iface.h

@@ -27 +27 @@
  */
 
-/** @addtogroup libdrv usb
+/** @addtogroup libdrv
+ * @addtogroup usb
  * @{
  */

uspace/lib/usb/include/usb/classes/classes.h

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/include/usb/classes/hid.h

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/include/usb/classes/hidparser.h

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/include/usb/classes/hidut.h

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/include/usb/classes/hidutkbd.h

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/include/usb/classes/hub.h

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */
@@ -68 +68 @@
  *      For more information see Universal Serial Bus Specification Revision 1.1 chapter 11.16.2
  */
-typedef struct hub_descriptor_type{
+typedef struct usb_hub_descriptor_type {
     /** Number of bytes in this descriptor, including this byte */
     //uint8_t bDescLength;

uspace/lib/usb/include/usb/debug.h

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */
@@ -45 +45 @@
 
 #endif
+/**
+ * @}
+ */
+

uspace/lib/usb/include/usb/descriptor.h

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/include/usb/devreq.h

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/include/usb/hcd.h

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */
@@ -81 +81 @@
     devman_handle_t);
 
-
 #endif
+/**
+ * @}
+ */

uspace/lib/usb/include/usb/hcdhubd.h

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/include/usb/usb.h

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/include/usb/usbdrv.h

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/src/addrkeep.c

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/src/class.c

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/src/debug.c

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/src/dp.c

@@ -45 +45 @@
  * @param data Parser data.
  * @param ptr Pointer to be verified.
- * @return Whether @ptr points inside <code>data->data</code> field.
+ * @return Whether @p ptr points inside <code>data->data</code> field.
  */
 static bool is_valid_descriptor_pointer(usb_dp_parser_data_t *data,

uspace/lib/usb/src/drvpsync.c

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/src/hcdhubd.c

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/src/hcdhubd_private.h

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/src/hcdrv.c

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/src/hidparser.c

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/src/localdrv.c

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/src/recognise.c

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */
@@ -39 +39 @@
 #include <errno.h>
 
+/** Callback for getting host controller handle.
+ *
+ * @param dev Device in question.
+ * @param[out] handle Devman handle of the host controller.
+ * @return Error code.
+ */
 static int usb_iface_get_hc_handle(device_t *dev, devman_handle_t *handle)
 {
@@ -237 +243 @@
  * @param matches Match ids list to add matches to.
  * @param address USB address of the attached device.
+ * @param config_count Number of configurations the device has.
  * @return Error code.
  */
@@ -342 +349 @@
 /** Probe for device kind and register it in devman.
  *
- * @param hc Open phone to the host controller.
- * @param parent Parent device.
- * @param address Address of the (unknown) attached device.
+ * @param[in] hc Open phone to the host controller.
+ * @param[in] parent Parent device.
+ * @param[in] address Address of the (unknown) attached device.
+ * @param[out] child_handle Handle of the child device.
  * @return Error code.
  */

uspace/lib/usb/src/remotedrv.c

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/src/usb.c

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/src/usbdrv.c

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */

uspace/lib/usb/src/usbdrvreq.c

@@ -27 +27 @@
  */
 
-/** @addtogroup libusb usb
+/** @addtogroup libusb
  * @{
  */
@@ -188 +188 @@
  * @param[in] phone Open phone to HC driver.
  * @param[in] old_address Current address.
- * @param[in] address Address to be set.
+ * @param[in] new_address Address to be set.
  * @return Error code.
  */

uspace/lib/usbvirt/src/main.c

@@ -183 +183 @@
 /** Create necessary phones for communication with virtual HCD.
  * This function wraps following calls:
- * -# open <code>/dev/devices/\\virt\\usbhc for reading
+ * -# open <code>/dev/devices/\\virt\\usbhc</code> for reading
  * -# access phone of file opened in previous step
  * -# create callback through just opened phone