[prev in list] [next in list] [prev in thread] [next in thread] 

List:       linux-kernel
Subject:    Re: [PATCH] docs: driver-model: bus.rst: Clean up the formatting, expound, modernize
From:       Jonathan Corbet <corbet () lwn ! net>
Date:       2021-01-11 20:31:58
Message-ID: 20210111133158.34923b4c () lwn ! net
[Download RAW message or body]

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


[prev in list] [next in list] [prev in thread] [next in thread]