Re: [PATCH] docs: driver-model: bus.rst: Clean up the formatting, expound, modernize
From: Jonathan Corbet <corbet@lwn.net>
Date: 2021-01-11 20:32:56
Also in:
lkml
On Mon, 21 Dec 2020 07:52:00 -0000 Michael Witten [off-list ref] 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 <redacted> --- 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...
quoted hunk ↗ jump to hunk
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