[src/trunk]: src/share/man/man9 Move DESCRIPTION below SYNOPSIS.

[wiz <wiz%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/3ac22b6b49bc
branches:  trunk
changeset: 779249:3ac22b6b49bc
user:      wiz <wiz%NetBSD.org@localhost>
date:      Sun May 13 11:57:39 2012 +0000

description:
Move DESCRIPTION below SYNOPSIS.
Remove function descriptions from SYNOPSIS.
Some cleanup while here.
XXX: most functions lack descriptions.

diffstat:

 share/man/man9/usbdi.9 |  210 ++++++++++++++++++++++++------------------------
 1 files changed, 106 insertions(+), 104 deletions(-)

diffs (truncated from 346 to 300 lines):

diff -r 92fe97febb4d -r 3ac22b6b49bc share/man/man9/usbdi.9
--- a/share/man/man9/usbdi.9    Sun May 13 11:57:05 2012 +0000
+++ b/share/man/man9/usbdi.9    Sun May 13 11:57:39 2012 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: usbdi.9,v 1.10 2012/05/13 10:57:09 mrg Exp $
+.\"    $NetBSD: usbdi.9,v 1.11 2012/05/13 11:57:39 wiz Exp $
 .\"
 .\" Copyright (c) 2012 Matthew R. Green
 .\" All rights reserved.
@@ -64,69 +64,7 @@
 .In dev/usb/usb.h
 .In dev/usb/usbdi.h
 .In dev/usb/usbdi_util.h
-.Sh DESCRIPTION
-Device driver access to the USB bus centers around transfers.
-A transfer describes a communication with a USB device.
-A transfer is an abstract concept that can result in several
-physical packets being transferred to or from a device.
-.Pp
-A transfer is described by a
-.Va usbd_xfer_handle ,
-a largely opaque cookie.
-Allocated and deallocate are performed with
-.Fn usbd_alloc_xfer
-and
-.Fn usbd_free_xfer .
-The data describing the transfer is filled by either
-.Fn usbd_setup_default_xfer
-for control pipe transfers, by
-.Fn usbd_setup_xfer
-for bulk and interrupt transfers, and by
-.Fn usbd_setup_isoc_xfer
-for isochronous transfers.
-.Pp
-A pipe is a logical connection to a USB device.
-Pipes are created and destroyed by using the
-.Fn usbd_open_pipe ,
-.Fn usbd_open_pipe_intr 
-and
-.Fn usbd_close_pipe
-functions.
-It is common to have more than one pipe per device.
-Pipes are used to allocate 
-.Va usbd_xfer_handle
-is required to 
-Transfers are aborted via their parent pipe with
-.Fn usbd_abort_pipe .
-The
-.Fn usbd_clear_endpoint_stall
-and
-.Fn usbd_clear_endpoint_stall_async
-functions are used to clear endpoint halt in either a synchronous
-or asynchronous fashion.
-The
-.Fn usbd_bulk_transfer
-and
-.Fn usbd_intr_transfer
-functions are used to transfer data in either an interrupt or
-bulk fashion.
-.Pp
-A request is described by a
-.Va usb_device_request_t
-which must be initialised as necessary before calling either
-.Fn usbd_do_request
-or
-.Fn usbd_do_request_flags
-to submit the request.
-See the
-.Sx INITIALISING USB REQUESTS
-section for more details.
-.Pp
-Error handling and other return values are described in
-.Xr usbd_status 9 .
-.Sh SYNOPSIS
 .Ss Functions offered by usbdi.h
-.Pp
 .Ft usbd_status
 .Fn usbd_open_pipe "usbd_interface_handle iface" "uint8_t address" \
  "uint8_t flags" "usbd_pipe_handle *pipe"
@@ -225,26 +163,10 @@
 .Fn usbd_set_polling" usbd_device_handle iface" "int val"
 .Ft const char *
 .Fn usbd_errstr "usbd_status err"
-Return the string associated with
-.Fa err .
 .Ft void
 .Fn usbd_add_dev_event "int type" "usbd_device_handle iface"
-The
-.Ar type
-must be one of
-.Dv USB_EVENT_CTRLR_ATTACH ,
-.Dv USB_EVENT_CTRLR_DETACH ,
-.Dv USB_EVENT_DEVICE_ATTACH
-and
-.Dv USB_EVENT_DEVICE_DETACH .
 .Ft void
 .Fn usbd_add_drv_event "int type" "usbd_device_handle iface" "device_t dv"
-The
-.Fa type
-must be one of
-.Dv USB_EVENT_DRIVER_ATTACH
-and
-.Dv USB_EVENT_DRIVER_DETACH .
 .Ft char *
 .Fn usbd_devinfo_alloc "usbd_device_handle iface" "int showclass"
 .Ft void
@@ -278,17 +200,12 @@
 .Ft const struct usb_devno *
 .Fn usb_lookup "const struct usb_devno *tbl" \
  "u_int16_t vendor" "u_int16_t product"
-The
-.Dv USB_PRODUCT_ANY
-macro can be used to match any USB product.
-.Pp
 .Ss Utilities from usbdi_util.h
 Based on the routines in
-.Dv "usbdi.h"
+.Dv usbdi.h
 a number of utility functions have been defined that are accessible
 through
-.Dv "usbdi_util.h"
-.Bl -tag -width indent
+.Dv usbdi_util.h .
 .Ft usbd_status
 .Fn usbd_get_desc "usbd_device_handle dev" "int type" "int index" \
  "int len" "void *desc"
@@ -336,8 +253,8 @@
 .Ft usbd_status
 .Fn usbd_get_config "usbd_device_handle dev" "uint8_t *conf"
 .Ft usbd_status
-.Fn usbd_get_string_desc "usbd_device_handle dev" "int sindex" "int langid"
-            usb_string_descriptor_t *sdesc"
+.Fn usbd_get_string_desc "usbd_device_handle dev" "int sindex" "int langid" \
+ "usb_string_descriptor_t *sdesc"
 .Ft void
 .Fn usbd_delay_ms "usbd_device_handle dev" "u_int ms"
 .Ft usbd_status
@@ -359,9 +276,95 @@
 .\" .Fn usb_detach_wait "device_t dv" "kcondvar_t *cv" "kmutex_t *lk"
 .\" .Ft void
 .\" .Fn usb_detach_broadcast "device_t dv" "kcondvar_t *cv"
+.Sh DESCRIPTION
+Device driver access to the USB bus centers around transfers.
+A transfer describes a communication with a USB device.
+A transfer is an abstract concept that can result in several
+physical packets being transferred to or from a device.
+.Pp
+A transfer is described by a
+.Va usbd_xfer_handle ,
+a largely opaque cookie.
+Allocated and deallocate are performed with
+.Fn usbd_alloc_xfer
+and
+.Fn usbd_free_xfer .
+The data describing the transfer is filled by either
+.Fn usbd_setup_default_xfer
+for control pipe transfers, by
+.Fn usbd_setup_xfer
+for bulk and interrupt transfers, and by
+.Fn usbd_setup_isoc_xfer
+for isochronous transfers.
+.Pp
+A pipe is a logical connection to a USB device.
+Pipes are created and destroyed by using the
+.Fn usbd_open_pipe ,
+.Fn usbd_open_pipe_intr
+and
+.Fn usbd_close_pipe
+functions.
+It is common to have more than one pipe per device.
+Pipes are used to allocate
+.Va usbd_xfer_handle
+is required to
+Transfers are aborted via their parent pipe with
+.Fn usbd_abort_pipe .
+The
+.Fn usbd_clear_endpoint_stall
+and
+.Fn usbd_clear_endpoint_stall_async
+functions are used to clear endpoint halt in either a synchronous
+or asynchronous fashion.
+The
+.Fn usbd_bulk_transfer
+and
+.Fn usbd_intr_transfer
+functions are used to transfer data in either an interrupt or
+bulk fashion.
+.Pp
+A request is described by a
+.Va usb_device_request_t
+which must be initialised as necessary before calling either
+.Fn usbd_do_request
+or
+.Fn usbd_do_request_flags
+to submit the request.
+See the
+.Sx INITIALISING USB REQUESTS
+section for more details.
+.Pp
+Error handling and other return values are described in
+.Xr usbd_status 9 .
+.Pp
+Comments on particular functions:
+.Bl -tag -width 10n
+.It Fn usbd_errstr err
+Return the string associated with
+.Fa err .
+.It Fn usbd_add_dev_event type iface
+The
+.Ar type
+must be one of
+.Dv USB_EVENT_CTRLR_ATTACH ,
+.Dv USB_EVENT_CTRLR_DETACH ,
+.Dv USB_EVENT_DEVICE_ATTACH
+and
+.Dv USB_EVENT_DEVICE_DETACH .
+.It Fn usbd_add_drv_event type iface dv
+The
+.Fa type
+must be one of
+.Dv USB_EVENT_DRIVER_ATTACH
+and
+.Dv USB_EVENT_DRIVER_DETACH .
+.It Fn usb_lookup tbl vendor product
+The
+.Dv USB_PRODUCT_ANY
+macro can be used to match any USB product.
 .El
 .Sh INITIALISING USB REQUESTS
-There are 5 members of a 
+There are 5 members of a
 .Va usb_device_request_t
 that must be initialised:
 .Pp
@@ -380,7 +383,7 @@
 .Pp
 The first two are normal byte values that may be simply assigned,
 but the last three must be initialised with the
-.Dv USETW()
+.Fn USETW
 macro.
 .Pp
 The
@@ -389,20 +392,20 @@
 indended recipient of the request.
 .Pp
 This may be one of:
-.Bl -tag -offset offset -compact
+.Bl -tag -width UT_WRITEXX -offset offset -compact
 .It Dv UT_WRITE
 .It Dv UT_READ
 .El
 .Pp
 with one of:
-.Bl -tag -offset offset -compact
+.Bl -tag -width UT_STANDARDXX -offset offset -compact
 .It Dv UT_STANDARD
 .It Dv UT_CLASS
 .It Dv UT_VENDOR
 .El
 .Pp
 and with one of:
-.Bl -tag -offset offset -compact
+.Bl -tag -width UT_INTERFACEXX -offset offset -compact
 .It Dv UT_DEVICE
 .It Dv UT_INTERFACE
 .It Dv UT_ENDPOINT
@@ -410,7 +413,7 @@
 .El
 .Pp
 These are also in combinations as:
-.Bl -tag -offset offset -compact
+.Bl -tag -width UT_WRITE_VENDOR_INTERFACEXX -offset offset -compact
 .It Dv UT_READ_DEVICE
 .It Dv UT_READ_INTERFACE
 .It Dv UT_READ_ENDPOINT
@@ -437,8 +440,9 @@
 .Pp
 The
 .Fa bRequest
-describes which request is being made.  The available values are:
-.Bl -tag -offset offset -compact
+describes which request is being made.
+The available values are:
+.Bl -tag -width UR_GET_DESCRIPTORXX -offset offset -compact
 .It Dv UR_GET_STATUS
 .It Dv UR_CLEAR_FEATURE
 .It Dv UR_SET_FEATURE
@@ -458,9 +462,8 @@
 and
 .Fa wLength
 are device-specific values and must be initialised with the
-.Dv USETW()
+.Fn USETW
 macro.
-.Pp
 .Sh USB REQUEST TYPES AND STRUCTURES
 The
 .Dv UR_GET_STATUS
@@ -475,7 +478,7 @@