Improve documentation for README, Cargo.toml, and API

- Update README with inline example, features section, modern syntax
- Fix Cargo.toml documentation URL to point to docs.rs
- Add feature flag comments to Cargo.toml
- Add module and struct documentation to decoder.rs
- Expand Within iterator documentation with example
- Add file-level docs and comments to example files

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: oschwald

Cargo.toml

@@ -7,16 +7,19 @@ readme = "README.md"
 keywords = ["MaxMind", "GeoIP2", "GeoIP", "geolocation", "ip"]
 categories = ["database", "network-programming"]
 homepage = "https://github.com/oschwald/maxminddb-rust"
-documentation = "http://oschwald.github.io/maxminddb-rust/maxminddb/struct.Reader.html"
+documentation = "https://docs.rs/maxminddb"
 repository = "https://github.com/oschwald/maxminddb-rust"
 license = "ISC"
 include = ["/Cargo.toml", "/benches/*.rs", "/src/**/*.rs", "/README.md", "/LICENSE"]
 edition = "2021"
 
 [features]
 default = []
+# SIMD-accelerated UTF-8 validation during string decoding
 simdutf8 = ["dep:simdutf8"]
+# Memory-mapped file access for better performance in long-running applications
 mmap = ["memmap2"]
+# Skip UTF-8 validation for maximum performance (mutually exclusive with simdutf8)
 unsafe-str-decode = []
 
 [lib]

README.md

@@ -28,22 +28,52 @@ Add this to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-maxminddb = "0.26"
+maxminddb = "0.27"
 ```
 
-and this to your crate root:
+## Example
 
 ```rust
-extern crate maxminddb;
+use maxminddb::{geoip2, Reader};
+use std::net::IpAddr;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let reader = Reader::open_readfile("/path/to/GeoLite2-City.mmdb")?;
+
+    let ip: IpAddr = "89.160.20.128".parse()?;
+    let result = reader.lookup(ip)?;
+
+    if let Some(city) = result.decode::<geoip2::City>()? {
+        println!("Country: {}", city.country.iso_code.unwrap_or("N/A"));
+        println!("City: {}", city.city.names.english.unwrap_or("N/A"));
+    }
+
+    Ok(())
+}
 ```
 
-## API Documentation
+See the [examples](examples/) directory for more usage patterns.
 
-The API docs are on [Docs.rs](https://docs.rs/maxminddb/latest/maxminddb/struct.Reader.html).
+## Features
 
-## Example
+Optional features:
+
+- **`mmap`**: Memory-mapped file access for long-running applications
+- **`simdutf8`**: SIMD-accelerated UTF-8 validation
+- **`unsafe-str-decode`**: Skip UTF-8 validation (requires trusted data)
+
+Enable in `Cargo.toml`:
 
-See [`examples/lookup.rs`](https://github.com/oschwald/maxminddb-rust/blob/main/examples/lookup.rs) for a basic example.
+```toml
+[dependencies]
+maxminddb = { version = "0.27", features = ["mmap"] }
+```
+
+Note: `simdutf8` and `unsafe-str-decode` are mutually exclusive.
+
+## Documentation
+
+[API documentation on docs.rs](https://docs.rs/maxminddb)
 
 ## Benchmarks
 
@@ -64,10 +94,6 @@ If [gnuplot](http://www.gnuplot.info/) is installed, Criterion.rs can generate
 an HTML report displaying the results of the benchmark under
 `target/criterion/report/index.html`.
 
-Result of doing 100 random IP lookups:
-
-![](/assets/pdf_small.svg)
-
 ## Contributing
 
 Contributions welcome! Please fork the repository and open a pull request

examples/lookup.rs

@@ -1,12 +1,19 @@
+//! Basic IP lookup example.
+//!
+//! Usage: cargo run --example lookup <database.mmdb> <ip_address>
+
 use std::net::IpAddr;
 
 use maxminddb::geoip2;
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Parse command line arguments
     let mut args = std::env::args().skip(1);
     let db_path = args
         .next()
         .ok_or("First argument must be the path to the IP database")?;
+
+    // Open the database file
     let reader = maxminddb::Reader::open_readfile(db_path)?;
 
     let ip_str = args
@@ -16,15 +23,17 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
         .parse()
         .map_err(|e| format!("Invalid IP address '{}': {}", ip_str, e))?;
 
+    // Look up the IP address
     let result = reader.lookup(ip)?;
 
+    // Decode and display city data if present
     if let Some(city) = result.decode::<geoip2::City>()? {
         println!("City data for IP {}: {city:#?}", ip);
     } else {
         println!("No city data found for IP {}", ip);
     }
 
-    // Show the network (available regardless of whether data was found)
+    // The network is always available, even when no data is found
     let network = result.network()?;
     println!("Network: {}", network);
     Ok(())

examples/within.rs

@@ -1,30 +1,44 @@
+//! Iterate over networks within a CIDR range.
+//!
+//! Usage: cargo run --example within <database.mmdb> <cidr>
+//!
+//! Example: cargo run --example within GeoLite2-City.mmdb "89.160.20.0/24"
+
 use ipnetwork::IpNetwork;
 use maxminddb::{geoip2, Within};
 
 fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Parse command line arguments
     let mut args = std::env::args().skip(1);
     let db_path = args
         .next()
         .ok_or("First argument must be the path to the IP database")?;
+
+    // Open the database file
     let reader = maxminddb::Reader::open_readfile(db_path)?;
 
     let cidr_str = args.next().ok_or(
         "Second argument must be the IP address and mask in CIDR notation, e.g. 0.0.0.0/0 or ::/0",
     )?;
 
+    // Parse the CIDR notation
     let ip_net: IpNetwork = cidr_str
         .parse()
         .map_err(|e| format!("Invalid CIDR notation '{}': {}", cidr_str, e))?;
 
+    // Iterate over all networks within the specified range
     let mut n = 0;
     let iter: Within<_> = reader.within(ip_net, Default::default())?;
     for next in iter {
         let lookup = next?;
         let network = lookup.network()?;
+
+        // Skip networks without data
         let Some(info) = lookup.decode::<geoip2::City>()? else {
-            continue; // Skip networks without data
+            continue;
         };
 
+        // Display location hierarchy
         let continent = info.continent.code.unwrap_or("");
         let country = info.country.iso_code.unwrap_or("");
         let city = info.city.names.english.unwrap_or("");

src/decoder.rs

@@ -1,3 +1,12 @@
+//! Binary format decoder for MaxMind DB files.
+//!
+//! This module implements deserialization of the MaxMind DB binary format
+//! into Rust types via serde. The decoder handles all MaxMind DB data types
+//! including pointers, maps, arrays, and primitive types.
+//!
+//! Most users should not need to interact with this module directly.
+//! Use [`Reader::lookup()`](crate::Reader::lookup) for normal lookups.
+
 use log::debug;
 use serde::de::{self, DeserializeSeed, MapAccess, SeqAccess, Visitor};
 use serde::forward_to_deserialize_any;
@@ -47,6 +56,14 @@ enum Value<'a, 'de> {
     Array(ArrayAccess<'a, 'de>),
 }
 
+/// Low-level decoder for MaxMind DB binary data.
+///
+/// This decoder implements serde's `Deserializer` trait to convert
+/// MaxMind DB binary format into Rust types. It handles pointer
+/// resolution, type coercion, and nested data structures.
+///
+/// Most users should use [`LookupResult::decode()`](crate::LookupResult::decode)
+/// instead of this type directly.
 #[derive(Debug)]
 pub struct Decoder<'de> {
     buf: &'de [u8],

src/within.rs

@@ -85,9 +85,28 @@ pub(crate) struct WithinNode {
 
 /// Iterator over IP networks within a CIDR range.
 ///
-/// This iterator yields [`LookupResult`] for each network in the database
-/// that falls within the specified CIDR range. Use [`LookupResult::decode()`]
-/// to deserialize the data for each result.
+/// Created by [`Reader::within()`](crate::Reader::within) or
+/// [`Reader::networks()`](crate::Reader::networks). Yields
+/// [`LookupResult`] for each network in the database that falls
+/// within the specified range.
+///
+/// Networks are yielded in depth-first order through the search tree.
+/// Use [`LookupResult::decode()`](crate::LookupResult::decode) to
+/// deserialize the data for each result.
+///
+/// # Example
+///
+/// ```
+/// use maxminddb::{Reader, WithinOptions, geoip2};
+///
+/// let reader = Reader::open_readfile("test-data/test-data/GeoIP2-City-Test.mmdb").unwrap();
+/// for result in reader.within("89.160.20.0/24".parse().unwrap(), Default::default()).unwrap() {
+///     let lookup = result.unwrap();
+///     if let Some(city) = lookup.decode::<geoip2::City>().unwrap() {
+///         println!("{}: {:?}", lookup.network().unwrap(), city.city.names.english);
+///     }
+/// }
+/// ```
 #[derive(Debug)]
 pub struct Within<'de, S: AsRef<[u8]>> {
     pub(crate) reader: &'de Reader<S>,