Adds more doc

Cargo.toml

@@ -4,10 +4,10 @@ version = "0.0.1"
 authors = ["Tpt <thomas@pellissier-tanon.fr>"]
 license = "MIT/Apache-2.0"
 readme = "../README.md"
-keywords = ["RDF"]
+keywords = ["RDF", "N-Triples", "Turtle", "RDF/XML", "SPARQL"]
 repository = "https://github.com/Tpt/rudf"
 description = """
-An RDF library in Rust
+An RDF and SPARQL library in Rust
 """
 build = "build.rs"
 

src/model/dataset.rs

@@ -4,6 +4,22 @@ use std::io::Read;
 use Result;
 
 /// Trait for [RDF graphs](https://www.w3.org/TR/rdf11-concepts/#dfn-graph)
+///
+/// This crate currently provides a simple stand-alone in memory implementation of the `Graph` trait.
+///
+/// Usage example:
+/// ```
+/// use rudf::model::*;
+/// use rudf::store::MemoryGraph;
+/// use std::str::FromStr;
+///
+/// let graph = MemoryGraph::default();
+/// let ex = NamedNode::from_str("http://example.com").unwrap();
+/// let triple = Triple::new(ex.clone(), ex.clone(), ex.clone());
+/// graph.insert(&triple);
+/// let results: Vec<Triple> = graph.triples_for_subject(&ex.into()).unwrap().map(|t| t.unwrap()).collect();
+/// assert_eq!(vec![triple], results);
+/// ```
 pub trait Graph {
     type TriplesIterator: Iterator<Item = Result<Triple>>;
     type TriplesForSubjectIterator: Iterator<Item = Result<Triple>>;
@@ -13,10 +29,12 @@ pub trait Graph {
     type SubjectsForPredicateObjectIterator: Iterator<Item = Result<NamedOrBlankNode>>;
     type TriplesForObjectIterator: Iterator<Item = Result<Triple>>;
 
+    /// Returns all triples contained by the graph
     fn iter(&self) -> Result<Self::TriplesIterator> {
         self.triples()
     }
 
+    /// Returns all triples contained by the graph
     fn triples(&self) -> Result<Self::TriplesIterator>;
 
     fn triples_for_subject(
@@ -64,14 +82,19 @@ pub trait Graph {
 
     fn triples_for_object(&self, object: &Term) -> Result<Self::TriplesForObjectIterator>;
 
+    /// Checks if the graph contains the given triple
     fn contains(&self, triple: &Triple) -> Result<bool>;
 
+    /// Adds a triple to the graph
     fn insert(&self, triple: &Triple) -> Result<()>;
 
+    /// Removes a concrete triple from the graph
     fn remove(&self, triple: &Triple) -> Result<()>;
 
+    /// Returns the number of triples in this graph
     fn len(&self) -> Result<usize>;
 
+    /// Checks if this graph contains a triple
     fn is_empty(&self) -> Result<bool>;
 }
 
@@ -81,6 +104,31 @@ pub trait NamedGraph: Graph {
 }
 
 /// Trait for [RDF datasets](https://www.w3.org/TR/rdf11-concepts/#dfn-rdf-dataset)
+///
+/// This crate currently provides two implementation of the `Dataset` traits:
+/// * One in memory: `rudf::store::MemoryDataset`
+/// * One disk-based using [RocksDB](https://rocksdb.org/): `rudf::store::RocksDbDataset`
+///
+/// Usage example with `rudf::store::MemoryDataset`:
+/// ```
+/// use rudf::model::*;
+/// use rudf::store::MemoryDataset;
+/// use std::str::FromStr;
+///
+/// let dataset = MemoryDataset::default();
+/// let default_graph = dataset.default_graph();
+/// let ex = NamedNode::from_str("http://example.com").unwrap();
+/// let triple = Triple::new(ex.clone(), ex.clone(), ex.clone());
+/// default_graph.insert(&triple);
+/// let results: Vec<Quad> = dataset.quads_for_subject(&ex.into()).unwrap().map(|t| t.unwrap()).collect();
+/// assert_eq!(vec![triple.in_graph(None)], results);
+/// ```
+///
+/// The implementation backed by RocksDB could be built using `RocksDbDataset::open` and works just like its in-memory equivalent:
+/// ```
+/// use rudf::store::RocksDbDataset;
+/// let dataset = RocksDbDataset::open("foo.db");
+/// ```
 pub trait Dataset {
     type NamedGraph: NamedGraph;
     type DefaultGraph: Graph;
@@ -94,16 +142,23 @@ pub trait Dataset {
     type QuadsForPredicateObjectIterator: Iterator<Item = Result<Quad>>;
     type QuadsForObjectIterator: Iterator<Item = Result<Quad>>;
 
+    /// Returns an object for a [named graph](https://www.w3.org/TR/rdf11-concepts/#dfn-named-graph) of this dataset.
+    ///
+    /// This named graph may be empty if no triple is in the graph yet.
     fn named_graph(&self, name: &NamedOrBlankNode) -> Result<Self::NamedGraph>;
 
+    /// Returns an object for the [default graph](https://www.w3.org/TR/rdf11-concepts/#dfn-default-graph) of this dataset
     fn default_graph(&self) -> Self::DefaultGraph;
 
+    /// Returns a graph that is the union of all graphs contained in this dataset, including the default graph
     fn union_graph(&self) -> Self::UnionGraph;
 
+    /// Returns all quads contained by the graph
     fn iter(&self) -> Result<Self::QuadsIterator> {
         self.quads()
     }
 
+    /// Returns all quads contained by the graph
     fn quads(&self) -> Result<Self::QuadsIterator>;
 
     fn quads_for_subject(
@@ -141,14 +196,19 @@ pub trait Dataset {
 
     fn quads_for_object(&self, object: &Term) -> Result<Self::QuadsForObjectIterator>;
 
+    /// Checks if this dataset contains a given quad
     fn contains(&self, quad: &Quad) -> Result<bool>;
 
+    /// Adds a quad to this dataset
     fn insert(&self, quad: &Quad) -> Result<()>;
 
+    /// Removes a quad from this dataset
     fn remove(&self, quad: &Quad) -> Result<()>;
 
+    /// Returns the number of quads in this dataset
     fn len(&self) -> Result<usize>;
 
+    /// Checks if this dataset contains a quad
     fn is_empty(&self) -> Result<bool>;
 
     fn query(&self, query: impl Read) -> Result<QueryResult>;

src/model/mod.rs

@@ -1,4 +1,5 @@
-//! Implements data structures for [RDF 1.1 Concepts](https://www.w3.org/TR/rdf11-concepts/)
+//! Implements data structures for [RDF 1.1 Concepts](https://www.w3.org/TR/rdf11-concepts/).
+//!
 //! Inspired by [RDFjs](http://rdf.js.org/) and [Apache Commons RDF](http://commons.apache.org/proper/commons-rdf/)
 
 mod blank_node;

src/rio/mod.rs

@@ -1,3 +1,5 @@
+//! Implementations of serializers and deserializers for usual RDF syntaxes
+
 pub mod ntriples;
 pub mod turtle;
 pub(crate) mod utils;

src/rio/ntriples/mod.rs

@@ -67,6 +67,7 @@ impl<R: Read> Iterator for NTriplesIterator<R> {
     }
 }
 
+/// Reads a N-Triples file from a Rust `Read` and returns an iterator on the read `Triple`s
 pub fn read_ntriples<'a, R: Read + 'a>(source: R) -> impl Iterator<Item = Result<Triple>> {
     NTriplesIterator {
         buffer: String::default(),

src/rio/turtle/mod.rs

@@ -37,6 +37,9 @@ mod grammar {
         }
     }
 
+    /// Reads a Turtle file from a Rust `Read` and returns an iterator on the read `Triple`s
+    ///
+    /// Warning: this implementation has not been optimized yet and stores all the found triples in memory
     pub fn read_turtle<'a, R: Read + 'a>(
         source: R,
         base_uri: impl Into<Option<Url>>,

src/rio/xml.rs

@@ -12,6 +12,7 @@ use std::str::FromStr;
 use url::Url;
 use Result;
 
+/// Reads a RDF/XML file from a Rust `Read` and returns an iterator on the read `Triple`s
 pub fn read_rdf_xml(
     source: impl BufRead,
     base_uri: impl Into<Option<Url>>,

src/store/memory.rs

@@ -5,7 +5,41 @@ use store::numeric_encoder::*;
 use store::store::*;
 use Result;
 
+/// Memory based implementation of the `rudf::model::Dataset` trait.
+/// They are cheap to build using the `MemoryDataset::default()` method.
+///
+/// Usage example:
+/// ```
+/// use rudf::model::*;
+/// use rudf::store::MemoryDataset;
+/// use std::str::FromStr;
+///
+/// let dataset = MemoryDataset::default();
+/// let default_graph = dataset.default_graph();
+/// let ex = NamedNode::from_str("http://example.com").unwrap();
+/// let triple = Triple::new(ex.clone(), ex.clone(), ex.clone());
+/// default_graph.insert(&triple);
+/// let results: Vec<Quad> = dataset.quads_for_subject(&ex.into()).unwrap().map(|t| t.unwrap()).collect();
+/// assert_eq!(vec![triple.in_graph(None)], results);
+/// ```
 pub type MemoryDataset = StoreDataset<MemoryStore>;
+
+/// Memory based implementation of the `rudf::model::Graph` trait.
+/// They are cheap to build using the `MemoryGraph::default()` method.
+///
+/// Usage example:
+/// ```
+/// use rudf::model::*;
+/// use rudf::store::MemoryGraph;
+/// use std::str::FromStr;
+///
+/// let graph = MemoryGraph::default();
+/// let ex = NamedNode::from_str("http://example.com").unwrap();
+/// let triple = Triple::new(ex.clone(), ex.clone(), ex.clone());
+/// graph.insert(&triple);
+/// let results: Vec<Triple> = graph.triples_for_subject(&ex.into()).unwrap().map(|t| t.unwrap()).collect();
+/// assert_eq!(vec![triple], results);
+/// ```
 pub type MemoryGraph = StoreDefaultGraph<MemoryStore>;
 
 #[derive(Default)]

src/store/mod.rs

@@ -1,3 +1,5 @@
+//! Provides implementations of the `rudf::model::Graph` and `rudf::model::Dataset` traits.
+
 pub mod isomorphism;
 mod memory;
 mod numeric_encoder;

src/store/rocksdb.rs

@@ -15,6 +15,13 @@ use store::store::EncodedQuadsStore;
 use store::store::StoreDataset;
 use Result;
 
+/// `rudf::model::Dataset` trait implementation based on the [RocksDB](https://rocksdb.org/) key-value store
+///
+/// Usage example:
+/// ```
+/// use rudf::store::RocksDbDataset;
+/// let dataset = RocksDbDataset::open("example.db").unwrap();
+/// ```
 pub type RocksDbDataset = StoreDataset<RocksDbStore>;
 
 impl RocksDbDataset {