Add documentation regarding meta-features

Author: mulimoen

Cargo.toml

@@ -16,6 +16,10 @@ default = []
 mpio = ["mpi-sys", "hdf5-sys/mpio"]
 lzf = ["lzf-sys", "errno"]
 blosc = ["blosc-sys"]
+# The features with version numbers such as 1.10.3, 1.12.0 are metafeatures
+# and is only available when the HDF5 library is at least this version.
+# Features have_direct and have_parallel are also metafeatures and dependent
+# on the HDF5 library which is linked against.
 
 [workspace]
 members = [".", "hdf5-types", "hdf5-derive", "hdf5-sys", "hdf5-src"]

src/globals.rs

@@ -16,10 +16,10 @@ use hdf5_sys::{h5e, h5p, h5t};
 
 use crate::internal_prelude::*;
 
-#[cfg(dll_indirection)]
-pub struct H5GlobalConstant(&'static usize);
-#[cfg(not(dll_indirection))]
-pub struct H5GlobalConstant(&'static hdf5_sys::h5i::hid_t);
+pub struct H5GlobalConstant(
+    #[cfg(dll_indirection)] &'static usize,
+    #[cfg(not(dll_indirection))] &'static hdf5_sys::h5i::hid_t,
+);
 
 impl std::ops::Deref for H5GlobalConstant {
     type Target = hdf5_sys::h5i::hid_t;

src/lib.rs

@@ -1,3 +1,19 @@
+//! HDF5 for Rust.
+//!
+//! This crate provides thread-safe Rust bindings and high-level wrappers for the `HDF5`
+//! library API. Some of the features include:
+//!
+//! - Thread-safety with non-threadsafe libhdf5 builds guaranteed via reentrant mutexes.
+//! - Native representation of most HDF5 types, including variable-length strings and arrays.
+//! - Derive-macro for automatic mapping of user structs and enums to `HDF5` types.
+//! - Multi-dimensional array reading/writing interface via `ndarray`.
+//!
+//! Direct low-level bindings are also available and provided in the `hdf5-sys` crate.
+//!
+//! Requires `HDF5` library of version 1.8.4 or later. Newer versions will enable additional
+//! features of the library. Such items are marked in the documentation with a version number
+//! indicating the required version of `HDF5`. The `have_direct` and `have_parallel` features
+//! also indicates `HDF5` functionality.
 #![cfg_attr(feature = "cargo-clippy", warn(clippy::pedantic))]
 #![cfg_attr(feature = "cargo-clippy", warn(clippy::nursery))]
 #![cfg_attr(feature = "cargo-clippy", warn(clippy::all))]