Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
MIME-Version: 1.0
References: <20230803093418.51872-1-tmgross@umich.edu> <CANiq72nhsqWsxHKmyNWLtV8AwdA1hAq5ooyJ0WNVrnzRnpjAFA@mail.gmail.com>
 <CALNs47tYsLq8wo3aiqU5Kmi8OFJgf6cugiRLJNiXZGUYdaVojQ@mail.gmail.com>
In-Reply-To: <CALNs47tYsLq8wo3aiqU5Kmi8OFJgf6cugiRLJNiXZGUYdaVojQ@mail.gmail.com>
From:   Miguel Ojeda <miguel.ojeda.sandonis@gmail.com>
Date:   Thu, 3 Aug 2023 19:52:06 +0200
Message-ID: <CANiq72kRjdKMuvYEGnATBN_mNSREfCJk0i8q79amhiA_ZaMXBw@mail.gmail.com>
Subject: Re: [RFC PATCH 0/2] Generate API documentation for 'bindings' crate
To:     Trevor Gross <tmgross@umich.edu>
Cc:     Miguel Ojeda <ojeda@kernel.org>,
        Alex Gaynor <alex.gaynor@gmail.com>,
        Wedson Almeida Filho <wedsonaf@gmail.com>,
        Boqun Feng <boqun.feng@gmail.com>, Gary Guo <gary@garyguo.net>,
        =?UTF-8?Q?Bj=C3=B6rn_Roy_Baron?= <bjorn3_gh@protonmail.com>,
        Benno Lossin <benno.lossin@proton.me>,
        rust-for-linux@vger.kernel.org, linux-doc@vger.kernel.org,
        linux-kernel@vger.kernel.org
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Precedence: bulk

On Thu, Aug 3, 2023 at 5:35=E2=80=AFPM Trevor Gross <tmgross@umich.edu> wro=
te:
>
> 1. For anyone reading/writing abstractions, it's useful to quickly see
> how exactly bindgen did the C -> Rust mapping

Do you mean using the integrated search in the generated docs and that
that is faster than e.g. grepping the generated file?

> 2. Abstractions may want to link to the C side somehow, linking the
> bindings is an easier first step than linking to sphinx (in the future
> we may be able to do a bindings -> sphinx link)

We definitely/already want to link to the C side in some places (e.g.
all header links, and some docs that refer to the C side, etc.), so
this is definitely valuable. But the ideal solution would be linking
to the actual C docs, indeed. I think we should avoid duplicating the
C docs infrastructure, if that is the use case here.

For that, I proposed to the `rustdoc` maintainers taking a map of
references (strings) to external resources (URLs), e.g. via a JSON
file or similar. This would be useful for a bunch of projects / use
cases, and I think the maintainers saw value in the feature. In the
kernel, for instance, we would generate a list of links in the C side
(e.g. mapping the `foo()` string to a URL, so that then a reference
like [`foo()`] in the Rust docs would be mapped to that URL).

Writing the `rustdoc` RFC has been in my backlog for a long time, but
if you would like to get involved, please let me know. It is a nice
time to come back to that, because the Rust docs are going to be in
kernel.org soon.

> Maybe a stronger "prefer abstractions over bindings" message would
> suffice to discourage use outside of reference?

Not sure if you mean in the module documentation or elsewhere (if the
latter, we have that in the kernel docs already as a "should").

> In any case, I will put this behind a flag so it is not enabled by
> default. While I'm at it - is there value in adding a config option to
> pass `--document-private-items` to the kernel crate, or supporting
> `RUSTDOCFLAGS` like Cargo does?

Personally, what I would love to see is that the documentation allows
you to see the private items but keeps them hidden by default (and
this could be applied to the `bindings` discussion too).

That way, users of subsystems do not need to see docs for private
items, or implementation details, or `bindings`. But, when needed, one
can simply flip a switch and see those immediately.

This would provide most of the benefits, while keeping the amount of
knobs/variables to maintain (and to learn, for users that want those
docs) as low as possible. A potential downside is, of course, build
time.

However, as far as I understand, that is not possible right now with
`rustdoc`, but would be ideal for us (and I imagine other projects).

An alternative that does not require `rustdoc` changes is providing a
second render of the docs in a subpage, e.g. `private` or
`implementation` or similar. If we go this way, a "top bar" (similar
to the one in docs.rs or Elixir) in order to select the kernel version
could be interesting, and could also be useful for other things such
as the "private" switch or arch/config selection if we end up with
that.

> How would switching to the library work? Since that seems like a more
> involved discussion, would postprocesing `generated_bindings.rs` be
> acceptable instead? I have been playing around with a python script
> that extracts the `#[doc ...]` blocks and (1) fixes the escaping and
> (2) formats parameters and fixes their spacing, I could extract this
> to a separate patch if it may be a while before we can use the
> library.

I think it would be best to go for the switch directly, i.e. to try to
use the "official" feature first (it was added on our request... :)

> Ah thanks, it just looks a bit weird in the diff.

My pleasure!

Cheers,
Miguel