Add documentation

[mulimoen]

A lot of the items and functions in this crate are undocumented, and it is hard to understand how to use this crate (and hdf5) in the correct way for maximum performance.

We should minimally add documentation for most types and functions, to make the documentation on docs.rs as clear as possible. Doctests can be added to individual functions to illustrate basic principals.

Having a guide on how to use the crate to fit in with the hdf5 ecosystem would be nice. We could link the current examples, and add additional one for how to use chunking, performance pitfalls (compression on varlen arrays, SOA vs AOS), and related functionality/tips & tricks in h5py and other relevant locations.

[aldanor]

@mulimoen I was looking re: how we could improve our documentation, and one important thing that stands out is features/version/platform dependence. It would be nice if we could label things like tokio does it -- e.g., check out https://docs.rs/tokio/1.12.0/tokio/io/index.html and try to browse around to see how feature-gated modules, methods and types are annotated.

Here's some reading and examples on the topic:

• https://stackoverflow.com/a/61417700
• Expose all OS-specific modules in libstd doc. rust-lang/rust#43348
• async-std docs no longer build on recent nightlies rust-lang/rust#75100

Not sure we care much about platform dependence (there's just a little bit of divergence but not much really), however feature-gated APIs like blosc / lzf / mpio and, most importantly, HDF5-version-gated APIs could benefit greatly in the docs if they were documented as such. In this case, should we always build the docs with the latest HDF5 version we support (i.e. 1.12.1 now) and all features like blosc/lzf/mpio enabled?

[aldanor]

After a bit of pondering, I think that docs should be like serde / h5py - as in, leave docs.rs documentation as verbose as possible but leave it as API docs, and maintain a separate book (like https://github.com/serde-rs/serde-rs.github.io) in the style of h5py.org, with similar chapters. We can even snatch hdf5.rs domain although it's a bit costly, like €1.4k for 10 years :/ If some org wished to fund it, that would be cool of course.

[mulimoen]

Makes sense to have a book to show the high level usage of the library, and tie together the examples and the rest of the ecosystem such as h5py. .rs seems a bit expensive, maybe add a donation link and see whether there are any interested sponsors?

[mulimoen]

It would be great to include examples into our docs as per https://twitter.com/wcrichton/status/1456112165744615426

[robgjansen]

FWIW, I find myself wanting to use this crate but the lack of documentation keeps driving me back to python's h5py library. The idea to create a book along the lines of h5py is a great one and would make it much easier to get up to speed quickly.