Add documentation for lib.rs, mmap_blob.rs, examples

examples/count.rs

@@ -1,3 +1,6 @@
+// Count the number of nodes, ways and relations in a PBF file given as the
+// first command line argument.
+
 extern crate osmpbf;
 
 use osmpbf::*;

src/lib.rs

@@ -1,4 +1,73 @@
-//! A fast reader for the PBF file format (\*.osm.pbf) for OpenStreetMap data.
+/*!
+A fast reader for the OpenStreetMap PBF file format (\*.osm.pbf).
+
+## Usage
+
+Add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+osmpbf = "0.1"
+```
+
+and this to your crate root:
+
+```rust
+extern crate osmpbf;
+```
+
+## Example: Count ways
+
+Here's a simple example that counts all the OpenStreetMap way elements in a
+file:
+
+```rust
+extern crate osmpbf;
+
+use osmpbf::*;
+
+fn main() {
+    let reader = ElementReader::from_path("tests/test.osm.pbf").unwrap();
+    let mut ways = 0_u64;
+
+    // Increment the counter by one for each way.
+    reader.for_each(|element| {
+        if let Element::Way(_) = element {
+            ways += 1;
+        }
+    }).unwrap();
+
+    println!("Number of ways: {}", ways);
+}
+```
+
+## Example: Count ways in parallel
+
+In this second example, we also count the ways but make use of all cores by
+decoding the file in parallel:
+
+```rust
+use osmpbf::*;
+
+fn main() {
+    let reader = ElementReader::from_path("tests/test.osm.pbf").unwrap();
+
+    // Count the ways
+    let ways = reader.par_map_reduce(
+        |element| {
+            match element {
+                Element::Way(_) => 1,
+                _ => 0,
+            }
+        },
+        || 0_u64,      // Zero is the identity value for addition
+        |a, b| a + b   // Sum the partial results
+    ).unwrap();
+
+    println!("Number of ways: {}", ways);
+}
+```
+*/
 
 #![recursion_limit = "1024"]
 
@@ -32,4 +101,3 @@ pub mod block;
 pub mod dense;
 pub mod elements;
 pub mod mmap_blob;
-

src/mmap_blob.rs

@@ -14,21 +14,49 @@ use std::fs::File;
 use std::path::Path;
 
 
+/// A read-only memory map.
 pub struct Mmap {
     mmap: memmap::Mmap,
 }
 
 impl Mmap {
-    // The underlying file should not be modified while holding the memory map.
-    // See https://github.com/danburkert/memmap-rs/issues/25
+    /// Creates a memory map from a given file.
+    ///
+    /// # Safety
+    /// The underlying file should not be modified while holding the memory map.
+    /// See https://github.com/danburkert/memmap-rs/issues/25
+    ///
+    /// # Example
+    /// ```
+    /// use osmpbf::*;
+    ///
+    /// # fn foo() -> Result<()> {
+    /// let f = std::fs::File::open("tests/test.osm.pbf")?;
+    /// let mmap = unsafe { Mmap::from_file(&f)? };
+    /// # Ok(())
+    /// # }
+    /// ```
     pub unsafe fn from_file(file: &File) -> Result<Mmap> {
         memmap::Mmap::map(file)
             .map(|m| Mmap { mmap: m })
             .chain_err(|| "Could not create memory map from file")
     }
 
-    // The underlying file should not be modified while holding the memory map.
-    // See https://github.com/danburkert/memmap-rs/issues/25
+    /// Creates a memory map from a given path.
+    ///
+    /// # Safety
+    /// The underlying file should not be modified while holding the memory map.
+    /// See https://github.com/danburkert/memmap-rs/issues/25
+    ///
+    /// # Example
+    /// ```
+    /// use osmpbf::*;
+    ///
+    /// # fn foo() -> Result<()> {
+    /// let mmap = unsafe { Mmap::from_path("tests/test.osm.pbf")? };
+    /// # Ok(())
+    /// # }
+    /// ```
     pub unsafe fn from_path<P: AsRef<Path>>(path: P) -> Result<Mmap> {
         let file = File::open(&path)?;
         memmap::Mmap::map(&file)
@@ -36,6 +64,7 @@ impl Mmap {
             .chain_err(|| format!("Could not create memory map from path {}", path.as_ref().display()))
     }
 
+    /// Returns an iterator over the blobs in this memory map.
     pub fn blob_iter(&self) -> MmapBlobReader {
         MmapBlobReader::new(self)
     }
@@ -45,12 +74,15 @@ impl Mmap {
     }
 }
 
+/// A PBF blob from a memory map.
 pub struct MmapBlob<'a> {
     header: BlobHeader,
     data: &'a [u8],
 }
 
 impl<'a> MmapBlob<'a> {
+    /// Decodes the Blob and tries to obtain the inner content (usually a `HeaderBlock` or a
+    /// `PrimitiveBlock`). This operation might involve an expensive decompression step.
     pub fn decode(&'a self) -> Result<BlobDecode<'a>> {
         let blob: fileformat::Blob = protobuf::parse_from_bytes(self.data)
             .chain_err(|| "failed to parse Blob")?;
@@ -68,6 +100,7 @@ impl<'a> MmapBlob<'a> {
     }
 }
 
+/// A reader for memory mapped PBF files that allows iterating over `MmapBlob`s.
 #[derive(Clone)]
 pub struct MmapBlobReader<'a> {
     mmap: &'a Mmap,
@@ -76,6 +109,20 @@ pub struct MmapBlobReader<'a> {
 }
 
 impl<'a> MmapBlobReader<'a> {
+    /// Creates a new `MmapBlobReader`.
+    ///
+    /// # Example
+    /// ```
+    /// use osmpbf::*;
+    ///
+    /// # fn foo() -> Result<()> {
+    ///
+    /// let mmap = unsafe { Mmap::from_path("tests/test.osm.pbf")? };
+    /// let reader = MmapBlobReader::new(&mmap);
+    ///
+    /// # Ok(())
+    /// # }
+    /// ```
     pub fn new(mmap: &Mmap) -> MmapBlobReader {
         MmapBlobReader {
             mmap: mmap,