linux-kernel - Re: [PATCH v3] Expose the bus kernel docs to the build docs.

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] [day] [month] [year] [list]

Message-ID: <87sg4w1ahb.fsf@meer.lwn.net>
Date:   Mon, 15 Mar 2021 13:29:52 -0600
From:   Jonathan Corbet <corbet@....net>
To:     Wren Turkal <wt@...guintechs.org>
Cc:     Wren Turkal <wt@...guintechs.org>, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH v3] Expose the bus kernel docs to the build docs.

Wren Turkal <wt@...guintechs.org> writes:

> Before, the bus type related APIs that were defined in the
> include/linux/device/bus.h were not referenced anywhere in the docs, so
> I linked it to the bus types api documentation.

This should really be phrased in the imperative style as described in
Documentation/process/submitting-patches.rst.  I wouldn't ordinarily
reject a patch just for that, but...

> Signed-off-by: Wren Turkal <wt@...guintechs.org>
> ---
>  Documentation/driver-api/driver-model/bus.rst | 8 ++++++++
>  Documentation/driver-api/infrastructure.rst   | 3 +--
>  2 files changed, 9 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/driver-api/driver-model/bus.rst b/Documentation/driver-api/driver-model/bus.rst
> index 016b15a6e8ea..c53b01e95fd9 100644
> --- a/Documentation/driver-api/driver-model/bus.rst
> +++ b/Documentation/driver-api/driver-model/bus.rst
> @@ -1,3 +1,5 @@
> +.. _bus_types:
> +
>  =========
>  Bus Types
>  =========
> @@ -144,3 +146,9 @@ sysfs directory using::
>  
>  	int bus_create_file(struct bus_type *, struct bus_attribute *);
>  	void bus_remove_file(struct bus_type *, struct bus_attribute *);
> +
> +Functions and Structures
> +========================
> +
> +.. kernel-doc:: include/linux/device/bus.h
> +.. kernel-doc:: drivers/base/bus.c
> diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst
> index 683bd460e222..eb2a2c9e3c0c 100644
> --- a/Documentation/driver-api/infrastructure.rst
> +++ b/Documentation/driver-api/infrastructure.rst
> @@ -41,8 +41,7 @@ Device Drivers Base
>  .. kernel-doc:: drivers/base/platform.c
>     :export:
>  
> -.. kernel-doc:: drivers/base/bus.c
> -   :export:
> +:ref:`bus_types`

Rather than inserting labels and making explicit cross-references, it
seems better to just let automarkup do the work for you.  So instead of
the above line, something like:

   See also Documentation/driver-api/driver-model/bus.rst

Thanks,

jon