Re: [RFC PATCH 0/2] Generate API documentation for 'bindings' crate

[Miguel Ojeda]

On Thu, Aug 3, 2023 at 11:36 AM Trevor Gross <tmgross@xxxxxxxxx> wrote:
>
> The 'bindings' crate currently doesn't have API documentation available.
> With this change, it will be generated as part of the output of 'make
> rustdoc' (similar to the 'kernel' crate's docs,
> https://rust-for-linux.github.io/docs/kernel/).
>
> This patch is a RFC because there are a few questions:

I think the first question to answer would be whether we want to
expose `bindings`, i.e. what are the advantages/disadvantages?

If `kernel` were a "normal library", then I would say we shouldn't,
because users should not need to care; and, in addition, the goal is
that leaf modules do not need to access them directly.

But, as sometimes happen, it may still be quite useful for some
developers nevertheless (the same way documenting the internal/private
details could be).

So, it would be nice to have an overview from your point of view on
why it should be done (or not).

> 1. Do we want to make this the default, or a separate target/
>    configuration? I don't think there is much downside to always
>    generating.

One downside of doing it by default would be going against the "avoid
`bindings`" guideline (ideally rule).

Another one is render time (the C side is trying to reduce it), I
guess, especially if we keep adding headers over time.

> 2. The entire '.config' file could be included in the doc output, to
>    make it easy to tell what settings the documentation was generated
>    with. Would this be desired? Maybe with a '--cfg
>    include-dotcfg=".config"' flag so published docs would have the
>    option (unsure whether it may ever have sensitive information).

This may be useful orthogonally to rendering `bindings` or not.

> Bindgen is currently invoked with '--no-doc-comments', I think this may
> be because some blocks were mistakenly interpreted as doctests. Once we
> upgrade our bindgen version we might be able to remove this.

Yes, that is https://github.com/Rust-for-Linux/linux/issues/323 and
https://github.com/rust-lang/rust-bindgen/issues/2057, which led to
the addition of `process_comments` to `bindgen` in v0.63.0.

> Side note, 'rust/Makefile' seems to have a mix of tabs and spaces - is
> this intentional?

Yes, it is intentional. For instance, the command definitions use
spaces like the vast majority of the kernel `Makefile`s.

Cheers,
Miguel