Add documentation and generate readmes

6 files changed, 93 insertions, 1 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..0f381a9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,17 @@
+# nftnl
+
+Safe abstraction for [`libnftnl`]. Provides low-level userspace access to the in-kernel
+nf_tables subsystem. See [`nftnl-sys`] for the low level FFI bindings to the C library.
+
+Can be used to create and remove tables, chains, sets and rules from the nftables firewall,
+the successor to iptables.
+
+## Selecting version of `libnftnl`
+
+See the documentation for the corresponding sys crate for details: [`nftnl-sys`]
+This crate has the same features as the sys crate, and selecting version works the same.
+
+[`libnftnl`]: https://netfilter.org/projects/libnftnl/
+[`nftnl-sys`]: https://crates.io/crates/nftnl-sys
+
+License: MIT/Apache-2.0
diff --git a/nftnl-sys/Cargo.toml b/nftnl-sys/Cargo.toml
index 5d25e0d..fd684b7 100644
--- a/nftnl-sys/Cargo.toml
+++ b/nftnl-sys/Cargo.toml
@@ -5,6 +5,7 @@ authors = ["Mullvad VPN <admin@mullvad.net>", "Linus Färnstrand <linus@mullvad.
 license = "MIT/Apache-2.0"
 description = "Low level FFI bindings to libnftnl. Provides low-level userspace access to the in-kernel nf_tables subsystem"
 repository = "https://github.com/mullvad/nftnl-rs"
+readme = "README.md"
 keywords = ["nftables", "nft", "firewall", "iptables", "netfilter"]
 categories = ["network-programming", "os::unix-apis", "external-ffi-bindings", "no-std"]
 
diff --git a/nftnl-sys/README.md b/nftnl-sys/README.md
new file mode 100644
index 0000000..b775d26
--- /dev/null
+++ b/nftnl-sys/README.md
@@ -0,0 +1,35 @@
+# nftnl-sys
+
+Low level FFI bindings to [`libnftnl`], a userspace library providing a low-level netlink
+programming interface (API) to the in-kernel nf_tables subsystem.
+
+See [`nftnl`] for a higher level safe abstraction.
+
+## Linking to libmnl and libnftnl
+
+By default this crate uses pkg-config to find and link to its C dependencies, [`libmnl`] and
+[`libnftnl`]. To manually configure where to look for these libraries, set the environment
+variables `LIBMNL_LIB_DIR` and `LIBNFTNL_LIB_DIR` to point to the directories where `libmnl.so`
+(or `libmnl.a`) and `libnftnl.so` (or `libnftnl.a`) resides.
+
+## Selecting version of `libnftnl`
+
+This crate has bindings for most versions of [`libnftnl`]. All bindings are generated by
+[`bindgen`] via the `generate_bindings.sh` script in this repository.
+
+Only one version of `libnftnl` can be exposed via this crate. By default the crate exports the
+bindings for the oldest supported version (`libnftnl-1.0.6`). To get newer versions activate the
+corresponding features. See `Cargo.toml` for available features/versions.
+
+So for example, to get bindings to `libnftnl-1.0.9` depend on this crate like this:
+```toml
+[dependencies]
+nftnl = { version = "0.1", features = ["nftnl-1-0-9"] }
+```
+
+[`libnftnl`]: https://netfilter.org/projects/libnftnl/
+[`libmnl`]: https://netfilter.org/projects/libmnl/
+[`nftnl`]: https://crates.io/crates/nftnl
+[`bindgen`]: https://crates.io/crates/bindgen
+
+License: MIT/Apache-2.0
diff --git a/nftnl-sys/src/lib.rs b/nftnl-sys/src/lib.rs
index 3c0a75f..884f304 100644
--- a/nftnl-sys/src/lib.rs
+++ b/nftnl-sys/src/lib.rs
@@ -6,13 +6,37 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-//! Low level FFI bindings to [`libnftnl`]. a userspace library providing a low-level netlink
+//! Low level FFI bindings to [`libnftnl`], a userspace library providing a low-level netlink
 //! programming interface (API) to the in-kernel nf_tables subsystem.
 //!
 //! See [`nftnl`] for a higher level safe abstraction.
 //!
+//! # Linking to libmnl and libnftnl
+//!
+//! By default this crate uses pkg-config to find and link to its C dependencies, [`libmnl`] and
+//! [`libnftnl`]. To manually configure where to look for these libraries, set the environment
+//! variables `LIBMNL_LIB_DIR` and `LIBNFTNL_LIB_DIR` to point to the directories where `libmnl.so`
+//! (or `libmnl.a`) and `libnftnl.so` (or `libnftnl.a`) reside.
+//!
+//! # Selecting version of `libnftnl`
+//!
+//! This crate has bindings for most versions of [`libnftnl`]. All bindings are generated by
+//! [`bindgen`] via the `generate_bindings.sh` script in this repository.
+//!
+//! Only one version of `libnftnl` can be exposed via this crate. By default the crate exports the
+//! bindings for the oldest supported version (`libnftnl-1.0.6`). To get newer versions activate the
+//! corresponding features. See `Cargo.toml` for available features/versions.
+//!
+//! So for example, to get bindings to `libnftnl-1.0.9` depend on this crate like this:
+//! ```toml
+//! [dependencies]
+//! nftnl-sys = { version = "0.1", features = ["nftnl-1-0-9"] }
+//! ```
+//!
 //! [`libnftnl`]: https://netfilter.org/projects/libnftnl/
+//! [`libmnl`]: https://netfilter.org/projects/libmnl/
 //! [`nftnl`]: https://crates.io/crates/nftnl
+//! [`bindgen`]: https://crates.io/crates/bindgen
 
 #![no_std]
 #![cfg(target_os = "linux")]
diff --git a/nftnl/Cargo.toml b/nftnl/Cargo.toml
index fa9a9e3..867c8ff 100644
--- a/nftnl/Cargo.toml
+++ b/nftnl/Cargo.toml
@@ -5,6 +5,7 @@ authors = ["Mullvad VPN <admin@mullvad.net>", "Linus Färnstrand <linus@mullvad.
 license = "MIT/Apache-2.0"
 description = "Safe abstraction for libnftnl. Provides low-level userspace access to the in-kernel nf_tables subsystem"
 repository = "https://github.com/mullvad/nftnl-rs"
+readme = "../README.md"
 keywords = ["nftables", "nft", "firewall", "iptables", "netfilter"]
 categories = ["network-programming", "os::unix-apis", "api-bindings"]
 
diff --git a/nftnl/src/lib.rs b/nftnl/src/lib.rs
index 5bfb967..69cb1c8 100644
--- a/nftnl/src/lib.rs
+++ b/nftnl/src/lib.rs
@@ -6,6 +6,20 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Safe abstraction for [`libnftnl`]. Provides low-level userspace access to the in-kernel
+//! nf_tables subsystem. See [`nftnl-sys`] for the low level FFI bindings to the C library.
+//!
+//! Can be used to create and remove tables, chains, sets and rules from the nftables firewall,
+//! the successor to iptables.
+//!
+//! # Selecting version of `libnftnl`
+//!
+//! See the documentation for the corresponding sys crate for details: [`nftnl-sys`]
+//! This crate has the same features as the sys crate, and selecting version works the same.
+//!
+//! [`libnftnl`]: https://netfilter.org/projects/libnftnl/
+//! [`nftnl-sys`]: https://crates.io/crates/nftnl-sys
+
 pub extern crate nftnl_sys;
 
 #[macro_use]