ensure that everything has a documentation

api/src/dataset/test.rs

@@ -1,5 +1,4 @@
 //! Contains helper functions and macros for testing Dataset implementations
-#![allow(missing_docs)]
 
 use std::fmt::Debug;
 
@@ -10,14 +9,19 @@ use crate::quad::*;
 use crate::source::*;
 use lazy_static::lazy_static;
 
-lazy_static! {
-    pub static ref G1: NsTerm<'static>  = NS.get("G1").unwrap();
-    pub static ref G2: NsTerm<'static> = NS.get("G2").unwrap();
-    //
-    pub static ref DG: Option<NsTerm<'static>> = None;
-    pub static ref GN1: Option<NsTerm<'static>> = Some(*G1);
-    pub static ref GN2: Option<NsTerm<'static>> = Some(*G2);
+#[allow(missing_docs)]
+mod ns {
+    use super::*;
+    lazy_static! {
+        pub static ref G1: NsTerm<'static>  = NS.get("G1").unwrap();
+        pub static ref G2: NsTerm<'static> = NS.get("G2").unwrap();
+        //
+        pub static ref DG: Option<NsTerm<'static>> = None;
+        pub static ref GN1: Option<NsTerm<'static>> = Some(*G1);
+        pub static ref GN2: Option<NsTerm<'static>> = Some(*G2);
+    }
 }
+pub use ns::*;
 
 /// Generates an empty quad source.
 pub fn no_quad() -> impl QuadSource {
@@ -102,6 +106,7 @@ pub fn generalized_node_types_quads() -> impl QuadSource {
     v.into_iter().into_quad_source()
 }
 
+/// Prints d on stdout (for debugging purposes only)
 pub fn dump_dataset<D: Dataset>(d: &D)
 where
     for<'x> DTerm<'x, D>: Debug,

api/src/graph/adapter.rs

@@ -146,7 +146,7 @@ impl<D: Dataset, M: GraphNameMatcher + Copy> Graph for PartialUnionGraph<D, M> {
 /// I wrap a [`Dataset`] as a [`Graph`]
 /// corresponding to a specific graph (default or named) of the wrapped dataset.
 ///
-/// This graph is also [mutable](`MutableGraph`) if the underlying dataset is.
+/// This graph is also [mutable](MutableGraph) if the underlying dataset is.
 ///
 /// NB: this type is design to be the return type of [`Dataset::graph`] and [`Dataset::graph_mut`].
 /// It is not designed to be usable "from scratch".

api/src/graph/test.rs

@@ -1,34 +1,38 @@
 //! Contains helper functions and macros for testing Graph implementations
-#![allow(missing_docs)]
-
+use lazy_static::lazy_static;
 use std::fmt::Debug;
 
 use super::*;
 use crate::ns::*;
 use crate::source::*;
 use crate::term::*;
-use lazy_static::lazy_static;
 
+/// Shortcut type alias for self-sustained [`SimpleTerm`]
 pub type StaticTerm = SimpleTerm<'static>;
 
-pub const NS: Namespace<&str> = Namespace::new_unchecked_const("http://example.org/");
-lazy_static! {
-    pub static ref C1: NsTerm<'static> = NS.get("C1").unwrap();
-    pub static ref C2: NsTerm<'static> = NS.get("C2").unwrap();
-    pub static ref P1: NsTerm<'static> = NS.get("p1").unwrap();
-    pub static ref P2: NsTerm<'static> = NS.get("p2").unwrap();
-    pub static ref I1A: NsTerm<'static> = NS.get("I1A").unwrap();
-    pub static ref I1B: NsTerm<'static> = NS.get("I1B").unwrap();
-    pub static ref I2A: NsTerm<'static> = NS.get("I2A").unwrap();
-    pub static ref I2B: NsTerm<'static> = NS.get("I2B").unwrap();
+#[allow(missing_docs)]
+mod ns {
+    use super::*;
+    pub const NS: Namespace<&str> = Namespace::new_unchecked_const("http://example.org/");
+    lazy_static! {
+        pub static ref C1: NsTerm<'static> = NS.get("C1").unwrap();
+        pub static ref C2: NsTerm<'static> = NS.get("C2").unwrap();
+        pub static ref P1: NsTerm<'static> = NS.get("p1").unwrap();
+        pub static ref P2: NsTerm<'static> = NS.get("p2").unwrap();
+        pub static ref I1A: NsTerm<'static> = NS.get("I1A").unwrap();
+        pub static ref I1B: NsTerm<'static> = NS.get("I1B").unwrap();
+        pub static ref I2A: NsTerm<'static> = NS.get("I2A").unwrap();
+        pub static ref I2B: NsTerm<'static> = NS.get("I2B").unwrap();
+    }
+    pub const B1: BnodeId<&str> = BnodeId::new_unchecked_const("1");
+    pub const B2: BnodeId<&str> = BnodeId::new_unchecked_const("2");
+    pub const B3: BnodeId<&str> = BnodeId::new_unchecked_const("3");
+    pub const EN: LanguageTag<&str> = LanguageTag::new_unchecked_const("en");
+    pub const V1: VarName<&str> = VarName::new_unchecked_const("v1");
+    pub const V2: VarName<&str> = VarName::new_unchecked_const("v2");
+    pub const V3: VarName<&str> = VarName::new_unchecked_const("v3");
 }
-pub const B1: BnodeId<&str> = BnodeId::new_unchecked_const("1");
-pub const B2: BnodeId<&str> = BnodeId::new_unchecked_const("2");
-pub const B3: BnodeId<&str> = BnodeId::new_unchecked_const("3");
-pub const EN: LanguageTag<&str> = LanguageTag::new_unchecked_const("en");
-pub const V1: VarName<&str> = VarName::new_unchecked_const("v1");
-pub const V2: VarName<&str> = VarName::new_unchecked_const("v2");
-pub const V3: VarName<&str> = VarName::new_unchecked_const("v3");
+pub use ns::*;
 
 /// Generates an empty triple source.
 pub fn no_triple() -> impl TripleSource {
@@ -114,6 +118,7 @@ pub fn generalized_node_types_triples() -> impl TripleSource {
     v.into_iter().into_triple_source()
 }
 
+/// Prints g on stdout
 pub fn dump_graph<G: Graph>(g: &G)
 where
     for<'x> GTerm<'x, G>: Debug,

api/src/lib.rs

@@ -48,6 +48,7 @@
 //!
 //! [SPARQL]: https://www.w3.org/TR/sparql11-query/
 //! [Notation3]: https://www.w3.org/TeamSubmission/n3/
+#![deny(missing_docs)]
 
 pub mod dataset;
 pub mod graph;

api/src/source/_quad.rs

@@ -123,7 +123,7 @@ pub trait QuadSource {
         map::MapQuadSource { source: self, map }
     }
 
-    // Convert of quads in this source to triples (stripping the graph name).
+    /// Convert of quads in this source to triples (stripping the graph name).
     fn to_triples(self) -> convert::ToTriples<Self>
     where
         Self: Sized,

api/src/source/_triple.rs

@@ -123,7 +123,7 @@ pub trait TripleSource {
         map::MapTripleSource { source: self, map }
     }
 
-    // Convert of triples in this source to quads (belonging to the default graph).
+    /// Convert of triples in this source to quads (belonging to the default graph).
     #[inline]
     fn to_quads(self) -> convert::ToQuads<Self>
     where

c14n/src/rdfc10.rs

@@ -18,7 +18,7 @@ use crate::_permutations::for_each_permutation_of;
 use crate::hash::{HashFunction, Sha256, Sha384};
 
 /// Write into `w` a canonical N-quads representation of `d`, where
-/// + blank nodes are canonically [relabelled](`relabel`) with
+/// + blank nodes are canonically [relabelled](relabel) with
 ///   - the [SHA-256](Sha256) hash function,
 ///   - the [`DEFAULT_DEPTH_FACTOR`],
 ///   - the [`DEFAULT_PERMUTATION_LIMIT`];
@@ -30,7 +30,7 @@ pub fn normalize<D: Dataset, W: io::Write>(d: &D, w: W) -> Result<(), C14nError<
 }
 
 /// Write into `w` a canonical N-quads representation of `d`, where
-/// + blank nodes are canonically [relabelled](`relabel_sha384`) with
+/// + blank nodes are canonically [relabelled](relabel_sha384) with
 ///   - the [SHA-384](Sha384) hash function,
 ///   - the [`DEFAULT_DEPTH_FACTOR`],
 ///   - the [`DEFAULT_PERMUTATION_LIMIT`];
@@ -42,7 +42,7 @@ pub fn normalize_sha384<D: Dataset, W: io::Write>(d: &D, w: W) -> Result<(), C14
 }
 
 /// Write into `w` a canonical N-quads representation of `d`, where
-/// + blank nodes are canonically [relabelled](`relabel_with`) with
+/// + blank nodes are canonically [relabelled](relabel_with) with
 ///   - the [hash function](HashFunction) `H`,
 ///   - the given `depth_factor`,
 ///   - the given `permutation_limit`;

inmem/src/dataset.rs

@@ -1,3 +1,4 @@
+//! In-memory implementations of [`Dataset`]
 use std::collections::BTreeSet;
 use std::iter::{empty, once};
 
@@ -12,14 +13,15 @@ mod _iter;
 use _iter::*;
 
 /// A dataset with a single quad index (GSPO).
-/// Fast to load but slow to query, with a relatively low memory footprint.
+/// Fast to load but slow on some queries, with a relatively low memory footprint.
 #[derive(Clone, Debug, Default)]
 pub struct GenericLightDataset<TI: TermIndex> {
     terms: TI,
     quads: BTreeSet<[TI::Index; 4]>,
 }
 
 impl<TI: GraphNameIndex + Default> GenericLightDataset<TI> {
+    /// Construct an empty dataset
     pub fn new() -> Self {
         Self {
             terms: TI::default(),
@@ -203,6 +205,7 @@ pub struct GenericFastDataset<TI: GraphNameIndex> {
 }
 
 impl<TI: GraphNameIndex + Default> GenericFastDataset<TI> {
+    /// Construct an empty dataset
     pub fn new() -> Self {
         Self {
             terms: TI::default(),
@@ -539,7 +542,16 @@ impl<TI: GraphNameIndex + Default> CollectibleDataset for GenericFastDataset<TI>
 
 impl<TI: GraphNameIndex> SetDataset for GenericFastDataset<TI> {}
 
+/// A dataset with a single quad index (GSPO).
+/// Fast to load but slow on some queries, with a relatively low memory footprint.
+///
+/// Default configuration of [`GenericLightDataset`].
 pub type LightDataset = GenericLightDataset<SimpleTermIndex<u32>>;
+
+/// A heavily indexed dataset.
+/// Fast to query but slow to load, with a relatively high memory footprint.
+///
+/// Default configuration of [`GenericFastDataset`].
 pub type FastDataset = GenericFastDataset<SimpleTermIndex<u32>>;
 
 #[cfg(test)]

inmem/src/graph.rs

@@ -1,3 +1,4 @@
+//! In-memory implementations of [`Graph`]
 use std::collections::BTreeSet;
 use std::iter::{empty, once};
 
@@ -19,6 +20,7 @@ pub struct GenericLightGraph<TI: TermIndex> {
 }
 
 impl<TI: TermIndex + Default> GenericLightGraph<TI> {
+    /// Construct an empty graph
     pub fn new() -> Self {
         Self {
             terms: TI::default(),
@@ -151,6 +153,7 @@ pub struct GenericFastGraph<TI: TermIndex> {
 }
 
 impl<TI: TermIndex + Default> GenericFastGraph<TI> {
+    /// Construct an empty graph
     pub fn new() -> Self {
         Self {
             terms: TI::default(),
@@ -329,7 +332,16 @@ impl<TI: TermIndex + Default> CollectibleGraph for GenericFastGraph<TI> {
 
 impl<TI: TermIndex> SetGraph for GenericFastGraph<TI> {}
 
+/// A graph with a single triple index (SPO).
+/// Fast to load but slow to query, with a relatively low memory footprint.
+///
+/// Default configuration of [`GenericLightGraph`].
 pub type LightGraph = GenericLightGraph<SimpleTermIndex<u32>>;
+
+/// A heavily indexed graph.
+/// Fast to query but slow to load, with a relatively high memory footprint.
+///
+/// Default configuration of [`GenericFastGraph`].
 pub type FastGraph = GenericFastGraph<SimpleTermIndex<u32>>;
 
 #[cfg(test)]

inmem/src/index.rs

@@ -1,14 +1,18 @@
-//! A [`TermIndex`] is a bidirectional assocuation of [terms](`Term`) with short numeric [indices](`Index`).
+//! A [`TermIndex`] is a bidirectional assocuation of [terms](Term) with short numeric [indices](Index).
 use sophia_api::term::{FromTerm, GraphName, SimpleTerm, Term};
 use std::collections::hash_map::Entry;
 use std::collections::HashMap;
 use std::error::Error;
 
-/// Abstraction of the short numeric indices representing [terms](`Term`) in a [`TermIndex`].
+/// Abstraction of the short numeric indices representing [terms](Term) in a [`TermIndex`].
 pub trait Index: Copy + std::fmt::Debug + Ord {
+    /// The minimal value of this index type
     const ZERO: Self;
+    /// The maximal value of this index type
     const MAX: Self;
+    /// Convert from usize
     fn from_usize(other: usize) -> Self;
+    /// Convert to usize
     fn into_usize(self) -> usize;
 }
 
@@ -53,10 +57,13 @@ impl Index for u16 {
 
 //
 
-/// A [`TermIndex`] is a bidirectional association of [terms](`Term`) with short numeric [indices](`Index`).
+/// A [`TermIndex`] is a bidirectional association of [terms](Term) with short numeric [indices](Index).
 pub trait TermIndex {
+    /// The type of [`Term`]s contained in this [`TermIndex`]
     type Term: Term;
+    /// The type of [indices](Index) used by this [`TermIndex`]
     type Index: Index;
+    /// The type of error that this [`TermIndex`] may raise
     type Error: Error + 'static;
 
     /// Get the index corresponding to term `t`, if it exists.
@@ -71,7 +78,7 @@ pub trait TermIndex {
     /// Get the term corresponding to index `i`.
     ///
     /// # Precondition
-    /// `i` must have been returned previously by [`get_index`](TermIndex::get_index) or (`ensure_index`)(TermIndex::ensure_index),
+    /// `i` must have been returned previously by [`get_index`](TermIndex::get_index) or [`ensure_index`](TermIndex::ensure_index),
     /// otherwise this method may panic.
     fn get_term(&self, i: Self::Index) -> <Self::Term as Term>::BorrowTerm<'_>;
 }
@@ -87,7 +94,7 @@ pub trait GraphNameIndex: TermIndex {
     /// Get the graph name corresponding to index `i`.
     ///
     /// # Precondition
-    /// `i` must have been returned previously by [`get_index`](TermIndex::get_index) or (`ensure_index`)(TermIndex::ensure_index),
+    /// `i` must have been returned previously by [`get_index`](TermIndex::get_index) or [`ensure_index`](TermIndex::ensure_index),
     /// otherwise this method may panic.
     fn get_graph_name(&self, i: Self::Index) -> GraphName<<Self::Term as Term>::BorrowTerm<'_>> {
         if i == self.get_default_graph_index() {
@@ -115,17 +122,20 @@ pub struct SimpleTermIndex<I: Index> {
 }
 
 impl<I: Index> SimpleTermIndex<I> {
+    /// Construct an empty index
     pub fn new() -> Self {
         SimpleTermIndex {
             t2i: HashMap::new(),
             i2t: vec![],
         }
     }
 
+    /// The numver of terms in this index
     pub fn len(&self) -> usize {
         self.i2t.len()
     }
 
+    /// Whether this index is empty
     pub fn is_empty(&self) -> bool {
         self.len() == 0
     }
@@ -173,6 +183,7 @@ impl<I: Index> GraphNameIndex for SimpleTermIndex<I> {
     }
 }
 
+/// An error type to indicate that a [`SimpleTermIndex`] is full
 #[derive(thiserror::Error, Copy, Clone, Debug)]
 #[error("This TermIndex can not contain more terms")]
 pub struct TermIndexFullError();

inmem/src/lib.rs

@@ -6,6 +6,7 @@
 //! [Sophia]: https://docs.rs/sophia/latest/sophia/
 //! [RDF]: https://www.w3.org/TR/rdf-primer/
 //! [Linked Data]: http://linkeddata.org/
+#![deny(missing_docs)]
 
 pub mod dataset;
 pub mod graph;

iri/src/lib.rs

@@ -7,7 +7,7 @@
 //!
 //! # Feature gates
 //!
-//! - **test_data** exposes the [`test`](mod@test) module,
+//! - **test_data** exposes the [`test`](`mod@test`) module,
 //!   which contains arrays of good and bad IRIs,
 //!   useful for testing purposes, possibly in other crates.
 //!

iri/src/resolve.rs

@@ -94,7 +94,7 @@ impl<T: Deref<Target = str>> BaseIriRef<T> {
     /// Convert this to a [`BaseIri`].
     ///
     /// # Precondition
-    /// This [`BaseIriRef`] must be [absolute](`OxiriRef::is_absolute`)
+    /// This [`BaseIriRef`] must be [absolute](OxiriRef::is_absolute)
     pub fn to_base_iri(self) -> BaseIri<T> {
         assert!(self.is_absolute());
         BaseIri(Oxiri::try_from(self.0).unwrap())
@@ -117,7 +117,7 @@ impl<T: Deref<Target = str>> Deref for BaseIriRef<T> {
 //
 
 /// A trait for anything that can be resolved against a
-/// [`BaseIri`](`BaseIri::resolve`) or a [`BaseIriRef`](`BaseIriRef::resolve`).
+/// [`BaseIri`](BaseIri::resolve) or a [`BaseIriRef`](BaseIriRef::resolve).
 pub trait Resolvable<T: Borrow<str>>: Borrow<str> {
     /// The output type when joining to an absolute base.
     type OutputAbs;

isomorphism/src/lib.rs

@@ -45,6 +45,8 @@
 //! The choice has been made to accept this flaw,
 //! as such undistinguishable blank nodes are very rare in real data,
 //! and not particularly useful.
+#![deny(missing_docs)]
+
 mod dataset;
 mod graph;
 mod hash;

jsonld/src/options.rs

@@ -22,7 +22,7 @@ use crate::vocabulary::ArcIri;
 ///
 /// ## Developers
 ///
-/// * the generic parameter `L` is the type of the [document loader](`json_ld::Loader`)
+/// * the generic parameter `L` is the type of the [document loader](json_ld::Loader)
 #[derive(Default)]
 pub struct JsonLdOptions<L> {
     inner: InnerOptions,

jsonld/src/parser.rs

@@ -28,7 +28,7 @@ mod test;
 ///
 /// ## Developers
 ///
-/// * the generic parameter `L` is the type of the [document loader](`json_ld::Loader`)
+/// * the generic parameter `L` is the type of the [document loader](json_ld::Loader)
 ///   (determined by the `options` parameters)
 pub struct JsonLdParser<L = NoLoader> {
     options: JsonLdOptions<L>,