Re: [PATCH] docs: driver-model: bus.rst: Clean up the formatting, expound, modernize

[Jonathan Corbet <corbet@lwn.net>]

On Mon, 21 Dec 2020 07:52:00 -0000
Michael Witten <mfwitten@gmail.com> wrote:

> * The reStructuredText had some indentation issues.
> 
> * The HTML output was not properly formatted in places.
> 
> * Some of the details were lacking or needed clarification (especially
>   with regard to how a `struct bus_type` object should be defined).
> 
> * The sysfs example hierarchy appeared outdated; I've updated it with
>   output based on what my own system currently displays.
> 
> Signed-off-by: Michael Witten <mfwitten@gmail.com>
> ---
>  Documentation/driver-api/driver-model/bus.rst | 110 +++++++++++++--------
>  1 file changed, 67 insertions(+), 43 deletions(-)

Thanks for working to improve the docs.  I have a couple of requests,
though... 

> diff --git a/Documentation/driver-api/driver-model/bus.rst b/Documentation/driver-api/driver-model/bus.rst
> index 016b15a6e8ea..68a95389b1eb 100644
> --- a/Documentation/driver-api/driver-model/bus.rst
> +++ b/Documentation/driver-api/driver-model/bus.rst
> @@ -4,34 +4,58 @@ Bus Types
>  
>  Definition
>  ~~~~~~~~~~
> -See the kerneldoc for the struct bus_type.
> -
> -int bus_register(struct bus_type * bus);
> +* ``struct bus_type``;
> +* ``int bus_register(struct bus_type *bus);``

This should just be made into a literal block like the others.

>  Declaration
>  ~~~~~~~~~~~
>  
> -Each bus type in the kernel (PCI, USB, etc) should declare one static
> -object of this type. They must initialize the name field, and may
> -optionally initialize the match callback::
> +For each bus type (PCI, USB, etc), there should be code that defines
> +one object of type ``struct bus_type``:

It is better not to mark types as ``literal`` this way; the build system is
getting better at recognizing such things on its own and generating the
appropriate links.

[...]

>  Registration
>  ~~~~~~~~~~~~
>  
> -When a bus driver is initialized, it calls bus_register. This
> -initializes the rest of the fields in the bus object and inserts it
> -into a global list of bus types. Once the bus object is registered,
> +During initialization of a bus driver, ``bus_register()`` is called; this

*definitely* don't mark functions as literal in this way; simply say
 bus_register() and the Right Things will happen.

Thanks,

jon