[PATCH 04/22] gadget.rst: Enrich its ReST representation and add kernel-doc tag

[Mauro Carvalho Chehab]

The pandoc conversion is not perfect. Do handwork in order to:

- add a title to this chapter;
- use the proper warning and note markups;
- use kernel-doc to include Kernel header and c files;
- remove legacy notes with regards to DocBook;
- some other minor adjustments to make it better to read in
  text mode and in html.

Signed-off-by: Mauro Carvalho Chehab <mchehab at s-opensource.com>
---
 Documentation/driver-api/usb/gadget.rst | 69 +++++++++++++++++++++------------
 1 file changed, 45 insertions(+), 24 deletions(-)

diff --git a/Documentation/driver-api/usb/gadget.rst b/Documentation/driver-api/usb/gadget.rst
index 4fd9862f3f21..c4c76ebb51d3 100644
--- a/Documentation/driver-api/usb/gadget.rst
+++ b/Documentation/driver-api/usb/gadget.rst
@@ -1,3 +1,7 @@
+Linux-USB "Gadget" kernel mode API
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
 Introduction
 ============
 
@@ -175,16 +179,12 @@ the gadget, and submitting one or more *struct usb\_request* buffers to
 transfer data. Understand those four data types, and their operations,
 and you will understand how this API works.
 
-    **Note**
+.. Note::
 
-    This documentation was prepared using the standard Linux kernel
-    ``docproc`` tool, which turns text and in-code comments into SGML
-    DocBook and then into usable formats such as HTML or PDF. Other than
-    the "Chapter 9" data types, most of the significant data types and
-    functions are described here.
+    Other than the "Chapter 9" data types, most of the significant data
+    types and functions are described here.
 
-    However, docproc does not understand all the C constructs that are
-    used, so some relevant information is likely omitted from what you
+    However, some relevant information is likely omitted from what you
     are reading. One example of such information is endpoint
     autoconfiguration. You'll have to read the header file, and use
     example source code (such as that for "Gadget Zero"), to fully
@@ -192,10 +192,10 @@ and you will understand how this API works.
 
     The part of the API implementing some basic driver capabilities is
     specific to the version of the Linux kernel that's in use. The 2.6
-    kernel includes a *driver model* framework that has no analogue on
-    earlier kernels; so those parts of the gadget API are not fully
-    portable. (They are implemented on 2.4 kernels, but in a different
-    way.) The driver model state is another part of this API that is
+    and upper kernel versions include a *driver model* framework that has
+    no analogue on earlier kernels; so those parts of the gadget API are
+    not fully portable. (They are implemented on 2.4 kernels, but in a
+    different way.) The driver model state is another part of this API that is
     ignored by the kerneldoc tools.
 
 The core API does not expose every possible hardware feature, only the
@@ -301,18 +301,19 @@ USB 2.0 Chapter 9 Types and Constants
 -------------------------------------
 
 Gadget drivers rely on common USB structures and constants defined in
-the ``<linux/usb/ch9.h>`` header file, which is standard in Linux 2.6
-kernels. These are the same types and constants used by host side
+the :ref:`linux/usb/ch9.h <usb_chapter9>` header file, which is standard in
+Linux 2.6+ kernels. These are the same types and constants used by host side
 drivers (and usbcore).
 
-!Iinclude/linux/usb/ch9.h
 Core Objects and Methods
 ------------------------
 
 These are declared in ``<linux/usb/gadget.h>``, and are used by gadget
 drivers to interact with USB peripheral controller drivers.
 
-!Iinclude/linux/usb/gadget.h
+.. kernel-doc:: include/linux/usb/gadget.h
+   :internal:
+
 Optional Utilities
 ------------------
 
@@ -320,7 +321,12 @@ The core API is sufficient for writing a USB Gadget Driver, but some
 optional utilities are provided to simplify common tasks. These
 utilities include endpoint autoconfiguration.
 
-!Edrivers/usb/gadget/usbstring.c !Edrivers/usb/gadget/config.c
+.. kernel-doc:: drivers/usb/gadget/usbstring.c
+   :export:
+
+.. kernel-doc:: drivers/usb/gadget/config.c
+   :export:
+
 Composite Device Framework
 --------------------------
 
@@ -337,7 +343,12 @@ usb\_function*, which packages a user visible role such as "network
 link" or "mass storage device". Management functions may also exist,
 such as "Device Firmware Upgrade".
 
-!Iinclude/linux/usb/composite.h !Edrivers/usb/gadget/composite.c
+.. kernel-doc:: include/linux/usb/composite.h
+   :internal:
+
+.. kernel-doc:: drivers/usb/gadget/composite.c
+   :export:
+
 Composite Device Functions
 --------------------------
 
@@ -345,11 +356,21 @@ At this writing, a few of the current gadget drivers have been converted
 to this framework. Near-term plans include converting all of them,
 except for "gadgetfs".
 
-!Edrivers/usb/gadget/function/f\_acm.c
-!Edrivers/usb/gadget/function/f\_ecm.c
-!Edrivers/usb/gadget/function/f\_subset.c
-!Edrivers/usb/gadget/function/f\_obex.c
-!Edrivers/usb/gadget/function/f\_serial.c
+.. kernel-doc:: drivers/usb/gadget/function/f_acm.c
+   :export:
+
+.. kernel-doc:: drivers/usb/gadget/function/f_ecm.c
+   :export:
+
+.. kernel-doc:: drivers/usb/gadget/function/f_subset.c
+   :export:
+
+.. kernel-doc:: drivers/usb/gadget/function/f_obex.c
+   :export:
+
+.. kernel-doc:: drivers/usb/gadget/function/f_serial.c
+   :export:
+
 Peripheral Controller Drivers
 =============================
 
@@ -475,7 +496,7 @@ can also benefit non-OTG products.
 -  Also on the host side, a driver must support the OTG "Targeted
    Peripheral List". That's just a whitelist, used to reject peripherals
    not supported with a given Linux OTG host. *This whitelist is
-   product-specific; each product must modify ``otg_whitelist.h`` to
+   product-specific; each product must modify* ``otg_whitelist.h`` *to
    match its interoperability specification.*
 
    Non-OTG Linux hosts, like PCs and workstations, normally have some
-- 
2.9.3