docs for days

2 files changed, 117 insertions, 1 deletions

diff --git a/src/lib.rs b/src/lib.rs
index c0f742a..5f915cf 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -3,6 +3,7 @@
     elided_lifetimes_in_paths,
     explicit_outlives_requirements,
     missing_debug_implementations,
+    missing_docs,
     noop_method_call,
     single_use_lifetimes,
     trivial_casts,
@@ -20,7 +21,7 @@ use knuffel::{Decode, DecodeScalar};
 mod schema_schema;
 pub use schema_schema::SCHEMA_SCHEMA;
 
-pub trait BuildFromRef {
+pub(crate) trait BuildFromRef {
     fn ref_to(query: impl Into<String>) -> Self;
 }
 
@@ -30,14 +31,22 @@ fn get_id_from_ref(r#ref: &str) -> Option<&str> {
         .and_then(|r#ref| r#ref.strip_suffix(r#""]"#))
 }
 
+/// the schema itself
 #[derive(Debug, PartialEq, Eq, Default)]
 #[cfg_attr(feature = "parse-knuffel", derive(Decode))]
 pub struct Schema {
+    /// the document this schema defines
+    ///
+    /// this is redundant but it matches the schema document structure
     #[cfg_attr(feature = "parse-knuffel", knuffel(child))]
     pub document: Document,
 }
 
 impl Schema {
+    /// find the node matching the given ref
+    ///
+    /// # Panics
+    ///
     /// Panics if ref is not of the form `[id="foo"]`.
     #[must_use]
     pub fn resolve_node_ref(&self, r#ref: &str) -> Option<&Node> {
@@ -48,6 +57,10 @@ impl Schema {
             .find_map(|node| node.find_node_by_id(id))
     }
 
+    /// find the prop matching the given ref
+    ///
+    /// # Panics
+    ///
     /// Panics if ref is not of the form `[id="foo"]`.
     #[must_use]
     pub fn resolve_prop_ref(&self, r#ref: &str) -> Option<&Prop> {
@@ -58,6 +71,10 @@ impl Schema {
             .find_map(|node| node.find_prop_by_id(id))
     }
 
+    /// find the value matching the given ref
+    ///
+    /// # Panics
+    ///
     /// Panics if ref is not of the form `[id="foo"]`.
     #[must_use]
     pub fn resolve_value_ref(&self, r#ref: &str) -> Option<&Value> {
@@ -68,6 +85,10 @@ impl Schema {
             .find_map(|node| node.find_value_by_id(id))
     }
 
+    /// find the children matching the given ref
+    ///
+    /// # Panics
+    ///
     /// Panics if ref is not of the form `[id="foo"]`.
     #[must_use]
     pub fn resolve_children_ref(&self, r#ref: &str) -> Option<&Children> {
@@ -81,6 +102,11 @@ impl Schema {
 
 #[cfg(feature = "parse-knuffel")]
 impl Schema {
+    /// parse a KDL schema definition
+    ///
+    /// # Errors
+    ///
+    /// returns an error if knuffel can't parse the document as a Schema
     pub fn parse(
         schema_kdl: &str,
     ) -> Result<Self, knuffel::Error<impl knuffel::traits::ErrorSpan>> {
@@ -88,106 +114,146 @@ impl Schema {
     }
 }
 
+/// the schema document
 #[derive(Debug, PartialEq, Eq, Default)]
 #[cfg_attr(feature = "parse-knuffel", derive(Decode))]
 pub struct Document {
+    /// schema metadata
     #[cfg_attr(feature = "parse-knuffel", knuffel(child))]
     pub info: Info,
+    /// top-level node definitions
     #[cfg_attr(feature = "parse-knuffel", knuffel(children(name = "node")))]
     pub nodes: Vec<Node>,
 }
 
+/// schema metadata
 #[derive(Debug, PartialEq, Eq, Default)]
 #[cfg_attr(feature = "parse-knuffel", derive(Decode))]
 pub struct Info {
+    /// schema titles
     #[cfg_attr(feature = "parse-knuffel", knuffel(children(name = "title")))]
     pub title: Vec<TextValue>,
+    /// schema descriptions
     #[cfg_attr(feature = "parse-knuffel", knuffel(children(name = "description")))]
     pub description: Vec<TextValue>,
+    /// schema authors
     #[cfg_attr(feature = "parse-knuffel", knuffel(children(name = "author")))]
     pub authors: Vec<Person>,
+    /// schema contributors
     #[cfg_attr(feature = "parse-knuffel", knuffel(children(name = "contributor")))]
     pub contributors: Vec<Person>,
+    /// schema links
     #[cfg_attr(feature = "parse-knuffel", knuffel(children(name = "link")))]
     pub links: Vec<Link>,
+    /// schema licenses
     #[cfg_attr(feature = "parse-knuffel", knuffel(children(name = "license")))]
     pub licenses: Vec<License>,
+    /// schema publication date
     #[cfg_attr(feature = "parse-knuffel", knuffel(child))]
     pub published: Option<Date>,
+    /// schema modification date
     #[cfg_attr(feature = "parse-knuffel", knuffel(child))]
     pub modified: Option<Date>,
 }
 
+/// a text value with an optional language tag
 #[derive(Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "parse-knuffel", derive(Decode))]
 pub struct TextValue {
+    /// text itself
     #[cfg_attr(feature = "parse-knuffel", knuffel(argument))]
     pub text: String,
+    /// BCP 47 language tag
     #[cfg_attr(feature = "parse-knuffel", knuffel(property))]
     pub lang: Option<String>,
 }
 
+/// information about a schema author/contributor
 #[derive(Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "parse-knuffel", derive(Decode))]
 pub struct Person {
+    /// name
     #[cfg_attr(feature = "parse-knuffel", knuffel(argument))]
     pub name: String,
+    /// [ORCID](https://orcid.org)
     #[cfg_attr(feature = "parse-knuffel", knuffel(property))]
     pub orcid: Option<String>,
+    /// relevant links
     #[cfg_attr(feature = "parse-knuffel", knuffel(children(name = "link")))]
     pub links: Vec<Link>,
 }
 
+/// link related to specification metadata, with optional relationship and language tag
 #[derive(Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "parse-knuffel", derive(Decode))]
 pub struct Link {
+    /// URI/IRI of link target
     #[cfg_attr(feature = "parse-knuffel", knuffel(argument))]
     pub iri: String,
+    /// relationship of link to schema (`self`, `documentation`)
     #[cfg_attr(feature = "parse-knuffel", knuffel(property))]
     pub rel: Option<String>,
+    /// BCP 47 language tag
     #[cfg_attr(feature = "parse-knuffel", knuffel(property))]
     pub lang: Option<String>,
 }
 
+/// schema license information
 #[derive(Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "parse-knuffel", derive(Decode))]
 pub struct License {
+    /// license name
     #[cfg_attr(feature = "parse-knuffel", knuffel(argument))]
     pub name: String,
+    /// license [SPDX identifier](https://spdx.org/licenses/)
     #[cfg_attr(feature = "parse-knuffel", knuffel(property))]
     pub spdx: Option<String>,
+    /// links for license information
     #[cfg_attr(feature = "parse-knuffel", knuffel(children(name = "link")))]
     pub link: Vec<Link>,
 }
 
+/// date with optional time
 #[derive(Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "parse-knuffel", derive(Decode))]
 pub struct Date {
+    /// date
     #[cfg_attr(feature = "parse-knuffel", knuffel(argument))]
     pub date: String,
+    /// time
     #[cfg_attr(feature = "parse-knuffel", knuffel(property))]
     pub time: Option<String>,
 }
 
+/// schema for a node
 #[derive(Debug, PartialEq, Eq, Default)]
 #[cfg_attr(feature = "parse-knuffel", derive(Decode))]
 pub struct Node {
+    /// name of the node (applies to all nodes at this level if `None`)
     #[cfg_attr(feature = "parse-knuffel", knuffel(argument))]
     pub name: Option<String>,
+    /// id of the node (can be used for refs)
     #[cfg_attr(feature = "parse-knuffel", knuffel(property))]
     pub id: Option<String>,
+    /// human-readable description of the node's purpose
     #[cfg_attr(feature = "parse-knuffel", knuffel(property))]
     pub description: Option<String>,
+    /// KDL query from which to load node information instead of specifying it inline (allows for recursion)
     #[cfg_attr(feature = "parse-knuffel", knuffel(property))]
     pub ref_: Option<String>,
+    /// minimum number of occurrences of this node
     #[cfg_attr(feature = "parse-knuffel", knuffel(child, unwrap(argument)))]
     pub min: Option<usize>,
+    /// maximum number of occurrences of this node
     #[cfg_attr(feature = "parse-knuffel", knuffel(child, unwrap(argument)))]
     pub max: Option<usize>,
+    /// properties allowed on this node
     #[cfg_attr(feature = "parse-knuffel", knuffel(children(name = "prop")))]
     pub props: Vec<Prop>,
+    /// values allowed on this node
     #[cfg_attr(feature = "parse-knuffel", knuffel(children(name = "value")))]
     pub values: Vec<Value>,
+    /// children allowed on this node
     #[cfg_attr(feature = "parse-knuffel", knuffel(children(name = "children")))]
     pub children: Vec<Children>,
 }
@@ -241,19 +307,26 @@ impl BuildFromRef for Node {
     }
 }
 
+/// schema for a property
 #[derive(Debug, PartialEq, Eq, Default)]
 #[cfg_attr(feature = "parse-knuffel", derive(Decode))]
 pub struct Prop {
+    /// property key (applies to all properties in this node if `None`)
     #[cfg_attr(feature = "parse-knuffel", knuffel(argument))]
     pub key: Option<String>,
+    /// id of the property (can be used for refs)
     #[cfg_attr(feature = "parse-knuffel", knuffel(property))]
     pub id: Option<String>,
+    /// human-readable description of the property
     #[cfg_attr(feature = "parse-knuffel", knuffel(property))]
     pub description: Option<String>,
+    /// KDL query from which to load property information instead of specifying it inline (allows for recursion)
     #[cfg_attr(feature = "parse-knuffel", knuffel(property))]
     pub ref_: Option<String>,
+    /// whether or not this property is required
     #[cfg_attr(feature = "parse-knuffel", knuffel(child))]
     pub required: bool,
+    /// validations to apply to the property value
     #[cfg_attr(feature = "parse-knuffel", knuffel(children))]
     pub validations: Vec<Validation>,
 }
@@ -277,19 +350,26 @@ impl BuildFromRef for Prop {
     }
 }
 
+/// schema for a value
 #[derive(Debug, PartialEq, Eq, Default)]
 #[cfg_attr(feature = "parse-knuffel", derive(Decode))]
 pub struct Value {
+    /// id of the value (can be used for refs)
     #[cfg_attr(feature = "parse-knuffel", knuffel(property))]
     pub id: Option<String>,
+    /// human readable description of the value
     #[cfg_attr(feature = "parse-knuffel", knuffel(property))]
     pub description: Option<String>,
+    /// KDL query from which to load value information instead of specifying it inline (allows for recursion)
     #[cfg_attr(feature = "parse-knuffel", knuffel(property))]
     pub ref_: Option<String>,
+    /// minimum number of occurrences of this value
     #[cfg_attr(feature = "parse-knuffel", knuffel(child, unwrap(argument)))]
     pub min: Option<usize>,
+    /// maximum number of occurrences of this value
     #[cfg_attr(feature = "parse-knuffel", knuffel(child, unwrap(argument)))]
     pub max: Option<usize>,
+    /// validations to apply to this value
     #[cfg_attr(feature = "parse-knuffel", knuffel(children))]
     pub validations: Vec<Validation>,
 }
@@ -313,15 +393,20 @@ impl BuildFromRef for Value {
     }
 }
 
+/// schema for a node's children
 #[derive(Debug, PartialEq, Eq, Default)]
 #[cfg_attr(feature = "parse-knuffel", derive(Decode))]
 pub struct Children {
+    /// id for these children (can be used for refs)
     #[cfg_attr(feature = "parse-knuffel", knuffel(property))]
     pub id: Option<String>,
+    /// human readable description of these children
     #[cfg_attr(feature = "parse-knuffel", knuffel(property))]
     pub description: Option<String>,
+    /// KDL query from which to load children information instead of specifying it inline (allows for recursion)
     #[cfg_attr(feature = "parse-knuffel", knuffel(property))]
     pub ref_: Option<String>,
+    /// nodes which can appear as children
     #[cfg_attr(feature = "parse-knuffel", knuffel(children(name = "node")))]
     pub nodes: Vec<Node>,
 }
@@ -359,40 +444,70 @@ impl BuildFromRef for Children {
     }
 }
 
+/// a validation to apply to some value or property value
 #[derive(Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "parse-knuffel", derive(Decode))]
 pub enum Validation {
+    /// ensure the value is of the given type
     Type(#[cfg_attr(feature = "parse-knuffel", knuffel(argument))] String),
+    /// ensure the value is one of the given options
     Enum(#[cfg_attr(feature = "parse-knuffel", knuffel(arguments))] Vec<String>),
+    /// ensure the value matches the given regular expression
     Pattern(#[cfg_attr(feature = "parse-knuffel", knuffel(argument))] String),
+    /// ensure the value is of the given format
     Format(#[cfg_attr(feature = "parse-knuffel", knuffel(arguments))] Vec<Format>),
 }
 
+/// a format to ensure a value has
 #[derive(Clone, Debug, PartialEq, Eq)]
 #[cfg_attr(feature = "parse-knuffel", derive(DecodeScalar))]
 pub enum Format {
+    /// iso 8601 datetime string
     DateTime,
+    /// iso 8601 date string
     Date,
+    /// iso 8601 time string
     Time,
+    /// iso 8601 duration string
     Duration,
+    /// ieee 754-2008 decimal string
     Decimal,
+    /// iso 4217 currency code string
     Currency,
+    /// iso 3166-1 alpha-2 country code string
     Country2,
+    /// iso 3166-1 alpha-3 country code string
     Country3,
+    /// iso 3166-2 country subdivision code string
     CountrySubdivision,
+    /// rfc 5302 email address string
     Email,
+    /// rfc 6531 internationalized email address string
     IdnEmail,
+    /// rfc 1132 internet hostname string
     Hostname,
+    /// rfc 5890 internationalized internet hostname string
     IdnHostname,
+    /// rfc 2673 ipv4 address string
     Ipv4,
+    /// rfc 2373 ipv6 address string
     Ipv6,
+    /// rfc 3986 uri string
     Url,
+    /// rfc 3986 uri reference string
     UrlReference,
+    /// rfc 3987 iri string
     Irl,
+    /// rfc 3987 iri reference string
     IrlReference,
+    /// rfc 6750 uri template string
     UrlTemplate,
+    /// rfc 4122 uuid string
     Uuid,
+    /// regular expression string
     Regex,
+    /// base64 encoded string
     Base64,
+    /// KDL query string
     KdlQuery,
 }
diff --git a/src/schema_schema.rs b/src/schema_schema.rs
index 11ccb4e..c17eb89 100644
--- a/src/schema_schema.rs
+++ b/src/schema_schema.rs
@@ -5,6 +5,7 @@ use lazy_static::lazy_static;
 use super::*;
 
 lazy_static! {
+    /// the schema schema defined by [the canonical `kdl-schema.kdl`](https://github.com/kdl-org/kdl/blob/cc1da35435abbe2f7d0138310f89b18c55a292e7/examples/kdl-schema.kdl)
     pub static ref SCHEMA_SCHEMA: Schema = make_schema_schema();
 }