On Thu, Aug 3, 2023 at 5:35 PM Trevor Gross <tmgross@xxxxxxxxx> wrote: > > 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
