Write and publish docs

[geofft]

We should have docs for at least all public APIs, and published rustdocs linked from the README.

It's not super straightforward to use this repo with crates.io (you need a local checkout for getting to the target JSON file, see #1). docs.rs automatically publishes crates on crates.io; I'm not sure if we want to publish the crate for the sake of using that (+ getting into things like crater runs?), or just self-host docs. (I run enough websites that I'm not going to be sad about self-hosting docs somewhere....)

[alex]

I know you built some docs, can we make a checklist of all the public APIs visible in it, and then we can just go through and comment them, and then make sure we do the same going forward?

[geofft]

I'd like to mark bindings as #[doc(hidden)] since it's generated and kernel-version-specific, although there's a surprising amount of upstream kernel docs getting valiantly interpreted by Rustdoc.

• [ ] chrdev
  • [ ] Builder, two methods, and builder
  • [ ] Registration
  • [ ] File and one method
  • [ ] SeekFrom (we can probably copy the docs from std::io)
  • [ ] FileOperationsVtable and its constructor
  • [x] FileOperations, its three methods, and the VTABLE associated const
• [ ] filesystem
  • [ ] FileSystemRegistration
  • [ ] FileSystem
  • [ ] FileSystemFlags and five flags
  • [ ] fn register
• [x] printk
  • [x] LogLineWriter (although should this be #[doc(hidden)]? it's only exposed for printk! internals, right?)
  • [x] printk (same maybe?)
• [ ] sysctl
  • [ ] SysctlStorage and its two methods
  • [ ] possibly the implementations
  • [ ] Sysctl and its two methods
• [ ] user_ptr (still needs module-level docs)
  • [X] UserSlicePtr and its methods
  • [ ] UserSlicePtrReader and its method
  • [ ] UserSlicePtrWriter and its methods
• [X] error (module itself is not exported, so it needs no module-level docs)
  • [ ] Error and ideally the From impl
  • [ ] KernelResult
• [X] types (module itself is not exported)
  • [ ] Mode
  • [x] CStr and its constructor
  • [x] cstr!
• [x] kernel_module! and KernelModule

[Sawchord]

Hi, I would like to help writing the documentation.

However, at the moment it is very hard do build the documentation to begin with. I managed to build them by putting a cargo doc into the Kbuild file of the hello-world example.

Is there are simpler way?

[alex]

At this point all new development is happening on https://github.com/Rust-for-Linux/linux/. If you're interested in contributing to the docs, that's the place to start.