Documentation strategy: rustdoc, man pages, header files

I'd like to figure out a solid plan for documentation. Right now our header file is our documentation. That's got a bunch of disadvantages. It's one huge file, so it's hard to navigate. It can't hyperlink words or sentences, or apply styles. And it can't nicely group related functions (like _read/_write/_read_tls/_write_tls). However, it has one big advantage: The contents are auto-generated by inline doccomments.

For Rust code, the standard tool for generating documentation is rustdoc. This generates nicely organized docs for our project right now, but those docs refer to the Rust signatures for functions, not the C signatures. That makes it a non-starter as our primary documentation. But perhaps we can do something hacky like search-and-replacing the signatures in the generated rustdoc? Or perhaps we could convince rustdoc to add features to support FFI projects, though it would be a very significant change in the rustdoc model.

The more typical option is Unix-style man pages, maintained separately from the doccomments and turned into HTML for display on the web. I think long term this is probably the way to go, particularly as the API stabilizes and the documentation doesn't need updating as often. However, it's a shame to lose out on all the useful tooling and styling that rustdoc gives us.

Thoughts?

Review the current header file and its inline doccomments, then compare the generated rustdoc with the C signatures it documents. Evaluate the rustdoc and Unix-style man-page approaches described here, including whether either can preserve navigation, grouping, and web presentation. Done means a decided documentation strategy and an actionable plan.