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
  • FileOperations, its three methods, and the VTABLE associated const
• filesystem
  • FileSystemRegistration
  • FileSystem
  • FileSystemFlags and five flags
  • fn register
• printk
  • LogLineWriter (although should this be #[doc(hidden)]? it's only exposed for printk! internals, right?)
  • printk (same maybe?)
• sysctl
  • SysctlStorage and its two methods
  • possibly the implementations
  • Sysctl and its two methods
• user_ptr (still needs module-level docs)
  • UserSlicePtr and its methods
  • UserSlicePtrReader and its method
  • UserSlicePtrWriter and its methods
• error (module itself is not exported, so it needs no module-level docs)
  • Error and ideally the From impl
  • KernelResult
• types (module itself is not exported)
  • Mode
  • CStr and its constructor
  • cstr!
• 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.