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

Jonathan Corbet
2021-01-11T20:32:56Z

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