diff --git a/lib/src/io/mod.rs b/lib/src/io/mod.rs index a5f56828..884e53b7 100644 --- a/lib/src/io/mod.rs +++ b/lib/src/io/mod.rs @@ -1,4 +1,4 @@ -//! Utilities to read and write RDF graphs and datasets +//! Utilities to read and write RDF graphs and datasets. mod format; pub mod read; diff --git a/lib/src/io/read.rs b/lib/src/io/read.rs index 04699a90..0341e2f2 100644 --- a/lib/src/io/read.rs +++ b/lib/src/io/read.rs @@ -1,4 +1,4 @@ -//! Utilities to read RDF graphs and datasets +//! Utilities to read RDF graphs and datasets. use crate::io::{DatasetFormat, GraphFormat}; use crate::model::*; diff --git a/lib/src/io/write.rs b/lib/src/io/write.rs index 25a17788..11c10824 100644 --- a/lib/src/io/write.rs +++ b/lib/src/io/write.rs @@ -1,4 +1,4 @@ -//! Utilities to write RDF graphs and datasets +//! Utilities to write RDF graphs and datasets. use crate::error::invalid_input_error; use crate::io::{DatasetFormat, GraphFormat}; diff --git a/lib/src/lib.rs b/lib/src/lib.rs index a88b4bb7..c1eb8c04 100644 --- a/lib/src/lib.rs +++ b/lib/src/lib.rs @@ -1,6 +1,6 @@ //! Oxigraph is a graph database library implementing the [SPARQL](https://www.w3.org/TR/sparql11-overview/) standard. //! -//! Its goal is to provide a compliant, safe and fast graph on-disk database. +//! Its goal is to provide a compliant, safe and fast on-disk database. //! It also provides a set of utility functions for reading, writing, and processing RDF files. //! //! Oxigraph is in heavy development and SPARQL query evaluation has not been optimized yet. diff --git a/lib/src/sparql/algebra.rs b/lib/src/sparql/algebra.rs index c586a7e2..44542096 100644 --- a/lib/src/sparql/algebra.rs +++ b/lib/src/sparql/algebra.rs @@ -9,7 +9,7 @@ use spargebra::GraphUpdateOperation; use std::fmt; use std::str::FromStr; -/// A parsed [SPARQL query](https://www.w3.org/TR/sparql11-query/) +/// A parsed [SPARQL query](https://www.w3.org/TR/sparql11-query/). /// /// ``` /// use oxigraph::model::NamedNode; @@ -33,7 +33,7 @@ pub struct Query { } impl Query { - /// Parses a SPARQL query with an optional base IRI to resolve relative IRIs in the query + /// Parses a SPARQL query with an optional base IRI to resolve relative IRIs in the query. pub fn parse(query: &str, base_iri: Option<&str>) -> Result { let query = spargebra::Query::parse(query, base_iri)?; Ok(Self { @@ -88,7 +88,7 @@ impl<'a> TryFrom<&'a String> for Query { } } -/// A parsed [SPARQL update](https://www.w3.org/TR/sparql11-update/) +/// A parsed [SPARQL update](https://www.w3.org/TR/sparql11-update/). /// /// ``` /// use oxigraph::sparql::Update; @@ -106,7 +106,7 @@ pub struct Update { } impl Update { - /// Parses a SPARQL update with an optional base IRI to resolve relative IRIs in the query + /// Parses a SPARQL update with an optional base IRI to resolve relative IRIs in the query. pub fn parse(update: &str, base_iri: Option<&str>) -> Result { let update = spargebra::Update::parse(update, base_iri)?; Ok(Self { diff --git a/lib/src/sparql/mod.rs b/lib/src/sparql/mod.rs index e82418a6..cdf83ec8 100644 --- a/lib/src/sparql/mod.rs +++ b/lib/src/sparql/mod.rs @@ -154,8 +154,9 @@ impl QueryOptions { self } - /// Adds a custom SPARQL evaluation function + /// Adds a custom SPARQL evaluation function. /// + /// Example with a function serializing terms to N-Triples: /// ``` /// use oxigraph::store::Store; /// use oxigraph::model::*; diff --git a/lib/src/sparql/model.rs b/lib/src/sparql/model.rs index 835053af..734d91b8 100644 --- a/lib/src/sparql/model.rs +++ b/lib/src/sparql/model.rs @@ -11,18 +11,18 @@ use std::io::{BufRead, Write}; use std::rc::Rc; use std::{fmt, io}; -/// Results of a [SPARQL query](https://www.w3.org/TR/sparql11-query/) +/// Results of a [SPARQL query](https://www.w3.org/TR/sparql11-query/). pub enum QueryResults { - /// Results of a [SELECT](https://www.w3.org/TR/sparql11-query/#select) query + /// Results of a [SELECT](https://www.w3.org/TR/sparql11-query/#select) query. Solutions(QuerySolutionIter), - /// Result of a [ASK](https://www.w3.org/TR/sparql11-query/#ask) query + /// Result of a [ASK](https://www.w3.org/TR/sparql11-query/#ask) query. Boolean(bool), - /// Results of a [CONSTRUCT](https://www.w3.org/TR/sparql11-query/#construct) or [DESCRIBE](https://www.w3.org/TR/sparql11-query/#describe) query + /// Results of a [CONSTRUCT](https://www.w3.org/TR/sparql11-query/#construct) or [DESCRIBE](https://www.w3.org/TR/sparql11-query/#describe) query. Graph(QueryTripleIter), } impl QueryResults { - /// Reads a SPARQL query results serialization + /// Reads a SPARQL query results serialization. pub fn read(reader: impl BufRead + 'static, format: QueryResultsFormat) -> io::Result { match format { QueryResultsFormat::Xml => read_xml_results(reader), @@ -34,9 +34,9 @@ impl QueryResults { } } - /// Writes the query results (solutions or boolean) + /// Writes the query results (solutions or boolean). /// - /// This method fails if it is called on the `Graph` results + /// This method fails if it is called on the `Graph` results. /// /// ``` /// use oxigraph::store::Store; @@ -65,9 +65,9 @@ impl QueryResults { } } - /// Writes the graph query results + /// Writes the graph query results. /// - /// This method fails if it is called on the `Solution` or `Boolean` results + /// This method fails if it is called on the `Solution` or `Boolean` results. /// /// ``` /// use oxigraph::store::Store; @@ -113,7 +113,7 @@ impl From for QueryResults { } } -/// [SPARQL query](https://www.w3.org/TR/sparql11-query/) results serialization formats +/// [SPARQL query](https://www.w3.org/TR/sparql11-query/) results serialization formats. #[derive(Eq, PartialEq, Debug, Clone, Copy, Hash)] #[non_exhaustive] pub enum QueryResultsFormat { @@ -222,7 +222,7 @@ impl QueryResultsFormat { } } -/// An iterator over [`QuerySolution`]s +/// An iterator over [`QuerySolution`]s. /// /// ``` /// use oxigraph::store::Store; @@ -249,14 +249,14 @@ impl QuerySolutionIter { Self { variables, iter } } - /// The variables used in the solutions + /// The variables used in the solutions. /// /// ``` /// use oxigraph::store::Store; /// use oxigraph::sparql::{QueryResults, Variable}; /// /// let store = Store::new()?; - /// if let QueryResults::Solutions(solutions) = store.query("SELECT ?s ?o WHERE { ?s ?p ?o }")? { + /// if let QueryResults::SolutionReturns all the quads contained in the stores(solutions) = store.query("SELECT ?s ?o WHERE { ?s ?p ?o }")? { /// assert_eq!(solutions.variables(), &[Variable::new("s")?, Variable::new("o")?]); /// } /// # Result::<_,Box>::Ok(()) @@ -367,7 +367,7 @@ impl VariableSolutionIndex for Variable { } } -/// An iterator over the triples that compose a graph solution +/// An iterator over the triples that compose a graph solution. /// /// ``` /// use oxigraph::store::Store; @@ -407,7 +407,7 @@ impl Iterator for QueryTripleIter { } } -/// A SPARQL query variable +/// A SPARQL query variable. /// /// ``` /// use oxigraph::sparql::Variable; diff --git a/lib/src/storage/backend/rocksdb.rs b/lib/src/storage/backend/rocksdb.rs index 78c68681..f3c9d874 100644 --- a/lib/src/storage/backend/rocksdb.rs +++ b/lib/src/storage/backend/rocksdb.rs @@ -1,4 +1,4 @@ -//! Code inspired by [https://github.com/rust-rocksdb/rust-rocksdb][Rust RocksDB] under Apache License 2.0. +//! Code inspired by [Rust RocksDB](https://github.com/rust-rocksdb/rust-rocksdb) under Apache License 2.0. //! //! TODO: still has some memory leaks if the database opening fails diff --git a/lib/src/store.rs b/lib/src/store.rs index 61420c11..cc5bafce 100644 --- a/lib/src/store.rs +++ b/lib/src/store.rs @@ -1,4 +1,4 @@ -//! API to access an on-on disk [RDF dataset](https://www.w3.org/TR/rdf11-concepts/#dfn-rdf-dataset). +//! API to access an on-disk [RDF dataset](https://www.w3.org/TR/rdf11-concepts/#dfn-rdf-dataset). //! //! Usage example: //! ``` @@ -41,7 +41,7 @@ use std::io::{BufRead, Write}; use std::path::Path; use std::{fmt, io, str}; -/// An on-on disk [RDF dataset](https://www.w3.org/TR/rdf11-concepts/#dfn-rdf-dataset). +/// An on-disk [RDF dataset](https://www.w3.org/TR/rdf11-concepts/#dfn-rdf-dataset). /// Allows to query and update it using SPARQL. /// It is based on the [RocksDB](https://rocksdb.org/) key-value store. /// @@ -85,14 +85,14 @@ pub struct Store { //TODO: indexes for the default graph and indexes for the named graphs (no more Optional and space saving) impl Store { - /// Creates a temporary [`Store`]() that will be deleted after drop. + /// Creates a temporary [`Store`] that will be deleted after drop. pub fn new() -> io::Result { Ok(Self { storage: Storage::new()?, }) } - /// Opens a [`Store`]() and creates it if it does not exist yet. + /// Opens a [`Store`] and creates it if it does not exist yet. #[cfg(not(target_arch = "wasm32"))] pub fn open(path: impl AsRef) -> io::Result { Ok(Self { @@ -174,25 +174,25 @@ impl Store { } } - /// Returns all the quads contained in the store + /// Returns all the quads contained in the store. pub fn iter(&self) -> QuadIter { self.quads_for_pattern(None, None, None, None) } - /// Checks if this store contains a given quad + /// Checks if this store contains a given quad. pub fn contains<'a>(&self, quad: impl Into>) -> io::Result { let quad = EncodedQuad::from(quad.into()); self.storage.snapshot().contains(&quad) } - /// Returns the number of quads in the store + /// Returns the number of quads in the store. /// - /// Warning: this function executes a full scan + /// Warning: this function executes a full scan. pub fn len(&self) -> io::Result { self.storage.snapshot().len() } - /// Returns if the store is empty + /// Returns if the store is empty. pub fn is_empty(&self) -> io::Result { self.storage.snapshot().is_empty() } @@ -239,7 +239,7 @@ impl Store { /// Loads a graph file (i.e. triples) into the store. /// - /// This function is atomic and quite slow and memory hungry. To get much better performances you might want to use [`bulk_load_graph`]. + /// This function is atomic and quite slow and memory hungry. To get much better performances you might want to use [`bulk_load_graph`](Store::bulk_load_graph). /// /// Usage example: /// ``` @@ -289,7 +289,7 @@ impl Store { /// Loads a dataset file (i.e. quads) into the store. /// - /// This function is atomic and quite slow. To get much better performances you might want to [`bulk_load_dataset`]. + /// This function is atomic and quite slow. To get much better performances you might want to [`bulk_load_dataset`](Store::bulk_load_dataset). /// /// Usage example: /// ``` @@ -358,7 +358,7 @@ impl Store { /// Adds atomically a set of quads to this store. /// - /// Warning: This operation uses a memory heavy transaction internally, use [`bulk_extend`] if you plan to add ten of millions of triples. + /// Warning: This operation uses a memory heavy transaction internally, use [`bulk_extend`](Store::bulk_extend) if you plan to add ten of millions of triples. pub fn extend(&self, quads: impl IntoIterator) -> io::Result<()> { let quads = quads.into_iter().collect::>(); self.storage.transaction(move |mut t| { @@ -491,7 +491,7 @@ impl Store { self.storage.snapshot().contains_named_graph(&graph_name) } - /// Inserts a graph into this store + /// Inserts a graph into this store. /// /// Returns `true` if the graph was not already in the store. /// @@ -592,10 +592,7 @@ impl Store { /// Flushes all buffers and ensures that all writes are saved on disk. /// - /// Flushes are automatically done for most platform using background threads. - /// However, calling this method explicitly is still required for Windows and Android. - /// - /// An [async version](SledStore::flush_async) is also available. + /// Flushes are automatically done using background threads but might lag a little bit. #[cfg(not(target_arch = "wasm32"))] pub fn flush(&self) -> io::Result<()> { self.storage.flush() @@ -613,7 +610,7 @@ impl Store { /// Loads a dataset file efficiently into the store. /// - /// This function is optimized for large dataset loading speed. For small files, [`load_dataset`] might be more convenient. + /// This function is optimized for large dataset loading speed. For small files, [`load_dataset`](Store::load_dataset) might be more convenient. /// /// Warning: This method is not atomic. If the parsing fails in the middle of the file, only a part of it may be written to the store. /// @@ -658,7 +655,7 @@ impl Store { /// Loads a dataset file efficiently into the store. /// - /// This function is optimized for large dataset loading speed. For small files, [`load_graph`] might be more convenient. + /// This function is optimized for large dataset loading speed. For small files, [`load_graph`](Store::load_graph) might be more convenient. /// /// Warning: This method is not atomic. If the parsing fails in the middle of the file, only a part of it may be written to the store. /// diff --git a/spargebra/src/parser.rs b/spargebra/src/parser.rs index 80e268cc..628747ec 100644 --- a/spargebra/src/parser.rs +++ b/spargebra/src/parser.rs @@ -15,7 +15,7 @@ use std::str::Chars; use std::str::FromStr; use std::{char, fmt}; -/// Parses a SPARQL query with an optional base IRI to resolve relative IRIs in the query +/// Parses a SPARQL query with an optional base IRI to resolve relative IRIs in the query. pub fn parse_query(query: &str, base_iri: Option<&str>) -> Result { let mut state = ParserState { base_iri: if let Some(base_iri) = base_iri { @@ -36,7 +36,7 @@ pub fn parse_query(query: &str, base_iri: Option<&str>) -> Result) -> Result { let mut state = ParserState { base_iri: if let Some(base_iri) = base_iri { diff --git a/spargebra/src/query.rs b/spargebra/src/query.rs index dbd33139..964b8a2d 100644 --- a/spargebra/src/query.rs +++ b/spargebra/src/query.rs @@ -5,7 +5,7 @@ use oxiri::Iri; use std::fmt; use std::str::FromStr; -/// A parsed [SPARQL query](https://www.w3.org/TR/sparql11-query/) +/// A parsed [SPARQL query](https://www.w3.org/TR/sparql11-query/). /// /// ``` /// use spargebra::Query; @@ -59,7 +59,7 @@ pub enum Query { } impl Query { - /// Parses a SPARQL query with an optional base IRI to resolve relative IRIs in the query + /// Parses a SPARQL query with an optional base IRI to resolve relative IRIs in the query. pub fn parse(query: &str, base_iri: Option<&str>) -> Result { parse_query(query, base_iri) } diff --git a/spargebra/src/update.rs b/spargebra/src/update.rs index 7bb20f9a..37829ab5 100644 --- a/spargebra/src/update.rs +++ b/spargebra/src/update.rs @@ -5,7 +5,7 @@ use oxiri::Iri; use std::fmt; use std::str::FromStr; -/// A parsed [SPARQL update](https://www.w3.org/TR/sparql11-update/) +/// A parsed [SPARQL update](https://www.w3.org/TR/sparql11-update/). /// /// ``` /// use spargebra::Update; @@ -25,7 +25,7 @@ pub struct Update { } impl Update { - /// Parses a SPARQL update with an optional base IRI to resolve relative IRIs in the query + /// Parses a SPARQL update with an optional base IRI to resolve relative IRIs in the query. pub fn parse(update: &str, base_iri: Option<&str>) -> Result { parse_update(update, base_iri) }