From 0c38774d9df48042dc50ef5821785322cee29b73 Mon Sep 17 00:00:00 2001 From: Pierre-Antoine Champin Date: Thu, 14 Dec 2023 08:49:39 +0100 Subject: [PATCH] ensure that everything has a documentation --- api/src/dataset/test.rs | 21 +++++++++++------- api/src/graph/adapter.rs | 2 +- api/src/graph/test.rs | 45 ++++++++++++++++++++++----------------- api/src/lib.rs | 1 + api/src/source/_quad.rs | 2 +- api/src/source/_triple.rs | 2 +- c14n/src/rdfc10.rs | 6 +++--- inmem/src/dataset.rs | 14 +++++++++++- inmem/src/graph.rs | 12 +++++++++++ inmem/src/index.rs | 21 +++++++++++++----- inmem/src/lib.rs | 1 + iri/src/lib.rs | 2 +- iri/src/resolve.rs | 4 ++-- isomorphism/src/lib.rs | 2 ++ jsonld/src/options.rs | 2 +- jsonld/src/parser.rs | 2 +- jsonld/src/serializer.rs | 6 +++--- sophia/src/lib.rs | 1 + turtle/src/lib.rs | 1 + xml/src/lib.rs | 2 +- 20 files changed, 100 insertions(+), 49 deletions(-) diff --git a/api/src/dataset/test.rs b/api/src/dataset/test.rs index a7e0e774..4c27b549 100644 --- a/api/src/dataset/test.rs +++ b/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> = None; - pub static ref GN1: Option> = Some(*G1); - pub static ref GN2: Option> = 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> = None; + pub static ref GN1: Option> = Some(*G1); + pub static ref GN2: Option> = 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: &D) where for<'x> DTerm<'x, D>: Debug, diff --git a/api/src/graph/adapter.rs b/api/src/graph/adapter.rs index 583d7aa4..97f05192 100644 --- a/api/src/graph/adapter.rs +++ b/api/src/graph/adapter.rs @@ -146,7 +146,7 @@ impl Graph for PartialUnionGraph { /// 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". diff --git a/api/src/graph/test.rs b/api/src/graph/test.rs index 0c0d624a..560cd3e0 100644 --- a/api/src/graph/test.rs +++ b/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: &G) where for<'x> GTerm<'x, G>: Debug, diff --git a/api/src/lib.rs b/api/src/lib.rs index 461428b1..4cf3d65d 100644 --- a/api/src/lib.rs +++ b/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; diff --git a/api/src/source/_quad.rs b/api/src/source/_quad.rs index 14356a95..a472e75c 100644 --- a/api/src/source/_quad.rs +++ b/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 where Self: Sized, diff --git a/api/src/source/_triple.rs b/api/src/source/_triple.rs index 80328ee8..e2553fb7 100644 --- a/api/src/source/_triple.rs +++ b/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 where diff --git a/c14n/src/rdfc10.rs b/c14n/src/rdfc10.rs index 2a078d21..2c922010 100644 --- a/c14n/src/rdfc10.rs +++ b/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: &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: &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`; diff --git a/inmem/src/dataset.rs b/inmem/src/dataset.rs index 194d7b23..33116def 100644 --- a/inmem/src/dataset.rs +++ b/inmem/src/dataset.rs @@ -1,3 +1,4 @@ +//! In-memory implementations of [`Dataset`] use std::collections::BTreeSet; use std::iter::{empty, once}; @@ -12,7 +13,7 @@ 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 { terms: TI, @@ -20,6 +21,7 @@ pub struct GenericLightDataset { } impl GenericLightDataset { + /// Construct an empty dataset pub fn new() -> Self { Self { terms: TI::default(), @@ -203,6 +205,7 @@ pub struct GenericFastDataset { } impl GenericFastDataset { + /// Construct an empty dataset pub fn new() -> Self { Self { terms: TI::default(), @@ -539,7 +542,16 @@ impl CollectibleDataset for GenericFastDataset impl SetDataset for GenericFastDataset {} +/// 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>; + +/// 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>; #[cfg(test)] diff --git a/inmem/src/graph.rs b/inmem/src/graph.rs index 35cc2c12..aa21688f 100644 --- a/inmem/src/graph.rs +++ b/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 { } impl GenericLightGraph { + /// Construct an empty graph pub fn new() -> Self { Self { terms: TI::default(), @@ -151,6 +153,7 @@ pub struct GenericFastGraph { } impl GenericFastGraph { + /// Construct an empty graph pub fn new() -> Self { Self { terms: TI::default(), @@ -329,7 +332,16 @@ impl CollectibleGraph for GenericFastGraph { impl SetGraph for GenericFastGraph {} +/// 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>; + +/// 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>; #[cfg(test)] diff --git a/inmem/src/index.rs b/inmem/src/index.rs index 22c92a85..8ce1c32b 100644 --- a/inmem/src/index.rs +++ b/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) -> ::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<::BorrowTerm<'_>> { if i == self.get_default_graph_index() { @@ -115,6 +122,7 @@ pub struct SimpleTermIndex { } impl SimpleTermIndex { + /// Construct an empty index pub fn new() -> Self { SimpleTermIndex { t2i: HashMap::new(), @@ -122,10 +130,12 @@ impl SimpleTermIndex { } } + /// 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 GraphNameIndex for SimpleTermIndex { } } +/// 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(); diff --git a/inmem/src/lib.rs b/inmem/src/lib.rs index f26c3ce3..3587c992 100644 --- a/inmem/src/lib.rs +++ b/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; diff --git a/iri/src/lib.rs b/iri/src/lib.rs index 75622dfe..ec434d48 100644 --- a/iri/src/lib.rs +++ b/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. //! diff --git a/iri/src/resolve.rs b/iri/src/resolve.rs index 29252c30..e889f8bd 100644 --- a/iri/src/resolve.rs +++ b/iri/src/resolve.rs @@ -94,7 +94,7 @@ impl> BaseIriRef { /// 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 { assert!(self.is_absolute()); BaseIri(Oxiri::try_from(self.0).unwrap()) @@ -117,7 +117,7 @@ impl> Deref for BaseIriRef { // /// 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>: Borrow { /// The output type when joining to an absolute base. type OutputAbs; diff --git a/isomorphism/src/lib.rs b/isomorphism/src/lib.rs index cfba3cde..de557b84 100644 --- a/isomorphism/src/lib.rs +++ b/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; diff --git a/jsonld/src/options.rs b/jsonld/src/options.rs index ce9bbc05..30a23d45 100644 --- a/jsonld/src/options.rs +++ b/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 { inner: InnerOptions, diff --git a/jsonld/src/parser.rs b/jsonld/src/parser.rs index 09d17bba..7ecd0d2b 100644 --- a/jsonld/src/parser.rs +++ b/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 { options: JsonLdOptions, diff --git a/jsonld/src/serializer.rs b/jsonld/src/serializer.rs index 6141baf7..b6ef5d99 100644 --- a/jsonld/src/serializer.rs +++ b/jsonld/src/serializer.rs @@ -22,7 +22,7 @@ mod test; /// ## Developers /// /// * the generic parameter `W` is the output type of the serializer (typically a [`std::io::Write`]) -/// * 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) pub struct JsonLdSerializer { options: JsonLdOptions, target: W, @@ -99,7 +99,7 @@ where /// /// ## 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 type Jsonifier = JsonLdSerializer; @@ -158,7 +158,7 @@ impl QuadSerializer for Jsonifier { /// /// ## 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 type JsonLdStringifier = JsonLdSerializer, L>; diff --git a/sophia/src/lib.rs b/sophia/src/lib.rs index d4803afd..6834d866 100644 --- a/sophia/src/lib.rs +++ b/sophia/src/lib.rs @@ -22,6 +22,7 @@ //! //! [RDF]: https://www.w3.org/TR/rdf-primer/ //! [Linked Data]: http://linkeddata.org/ +#![deny(missing_docs)] pub use sophia_api as api; pub use sophia_c14n as c14n; diff --git a/turtle/src/lib.rs b/turtle/src/lib.rs index e830d870..50c108b3 100644 --- a/turtle/src/lib.rs +++ b/turtle/src/lib.rs @@ -7,6 +7,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 parser; pub mod serializer; diff --git a/xml/src/lib.rs b/xml/src/lib.rs index c8ee6766..f81f4024 100644 --- a/xml/src/lib.rs +++ b/xml/src/lib.rs @@ -8,7 +8,7 @@ //! [RDF]: https://www.w3.org/TR/rdf-primer/ //! [Linked Data]: http://linkeddata.org/ //! [RDF/XML]: https://www.w3.org/TR/rdf-syntax-grammar/ +#![deny(missing_docs)] pub mod parser; - pub mod serializer;