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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20210111133158.34923b4c@lwn.net>
Date:   Mon, 11 Jan 2021 13:31:58 -0700
From:   Jonathan Corbet <corbet@....net>
To:     Michael Witten <mfwitten@...il.com>
Cc:     Mauro Carvalho Chehab <mchehab+samsung@...nel.org>,
        Jeff Kirsher <jeffrey.t.kirsher@...el.com>,
        linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH] docs: driver-model: bus.rst: Clean up the formatting,
 expound, modernize

On Mon, 21 Dec 2020 07:52:00 -0000
Michael Witten <mfwitten@...il.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@...il.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