Rust-for-Linux/linux

Move proc-macro documentation into the `kernel` crate

y86-dev opened this issue · 4 comments

y86-dev commented

Currently all examples in the macros crate are ignored, since they are depending on stuff from the kernel crate. There are several reasons for why we would like them to not be ignored:

  • It shows up in the documentation as "This example is not tested" and might confuse readers.
  • We should execute those examples as tests.
  • It helps keep them up-to date, since are need to compile.

A solution is to move the documentation from the macros crate into the kernel crate via using re-exports. When doing this, please also ensure that the tests compile.

This requires submitting a proper patch to the LKML and the Rust for Linux mailing list. Please recall to test your changes, to use a proper title for the commit, to sign your commit under the Developer's Certificate of Origin and so on. Please see https://docs.kernel.org/process/submitting-patches.html and https://rust-for-linux.com/contributing for details.

Please take this issue only if you are new to the kernel development process and you would like to use it as a test to submit your first patch to the kernel. Please do not take it if you do not plan to make other contributions to the kernel.

bjorn3 commented

It should be possible to build the macro crate as rmeta, then build the kernel crate as rmeta and finally rustdoc the macro crate with the kernel crate as dependency, right? It just needs both version of the macro crate to be compiled with different -Cmetadata arguments.

y86-dev commented

It should be possible to build the macro crate as rmeta, then build the kernel crate as rmeta and finally rustdoc the macro crate with the kernel crate as dependency, right? It just needs both version of the macro crate to be compiled with different -Cmetadata arguments.

Hmm I have no idea if that works, but if anyone wants to try it, feel free to do so.