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

Thu Mar 30 00:04:32 PDT 2017

On Thu, 30 Mar 2017, Jani Nikula <jani.nikula at linux.intel.com> wrote:
> On Wed, 29 Mar 2017, Mauro Carvalho Chehab <mchehab at s-opensource.com> wrote:
>> 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;
>
> Please look at Documentation/sphinx/tmplcvt which takes care of all of
> that.

That said, since you've already manually done the work, you might want
to do another conversion using the script, and diff the results to see
if there's something you've perhaps missed. I'm pretty sure nobody's
going to read patch 2 line-by-line...

BR,
Jani.

>
> BR,
> Jani.
>
>> - 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

-- 
Jani Nikula, Intel Open Source Technology Center