Add documentation to the info and includes modules.

src/includes/include_ref.rs

@@ -21,10 +21,10 @@
 use crate::data::PageRef;
 use crate::tree::VariableMap;
 
-/// Represents an include block.
+/// Represents an include block before it has been replaced with the fetched page.
 ///
-/// It contains the page being included, as well as the arguments
-/// to be passed to it when doing the substitution.
+/// It contains the page being included, as well as the variables passed to it in the include
+/// block.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
 #[serde(rename_all = "kebab-case")]
 pub struct IncludeRef<'t> {

src/includes/includer/debug.rs

@@ -20,9 +20,15 @@
 
 use super::prelude::*;
 use crate::tree::VariableMap;
+#[cfg(test)]
+use std::collections::HashMap;
 use std::convert::Infallible;
 use std::fmt::{self, Display};
 
+/// An [`Includer`] that replaces included references with the page content followed by the
+/// include variables and their values.
+///
+/// Useful for testing includes.
 #[derive(Debug)]
 pub struct DebugIncluder;
 

src/includes/includer/mod.rs

@@ -18,14 +18,16 @@
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
+//! This module contains tools which format pages after they have been referenced in an include
+//! block.
+
 mod debug;
 mod null;
 
 mod prelude {
     pub use crate::data::PageRef;
     pub use crate::includes::{FetchedPage, IncludeRef, Includer};
     pub use std::borrow::Cow;
-    pub use std::collections::HashMap;
 }
 
 use crate::includes::{IncludeRef, PageRef};
@@ -34,21 +36,25 @@ use std::borrow::Cow;
 pub use self::debug::DebugIncluder;
 pub use self::null::NullIncluder;
 
+/// A type used by [`Includer`] which represents a page that is ready to be included.
 #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
 #[serde(rename_all = "kebab-case")]
 pub struct FetchedPage<'t> {
     pub page_ref: PageRef<'t>,
     pub content: Option<Cow<'t, str>>,
 }
 
+/// A trait that handles the formatting of included pages.
 pub trait Includer<'t> {
     type Error;
 
+    /// Returns a list of the pages included.
     fn include_pages(
         &mut self,
         includes: &[IncludeRef<'t>],
     ) -> Result<Vec<FetchedPage<'t>>, Self::Error>;
 
+    /// Handles the inclusion of a page not found.
     fn no_such_include(
         &mut self,
         page_ref: &PageRef<'t>,

src/includes/includer/null.rs

@@ -21,6 +21,7 @@
 use super::prelude::*;
 use std::convert::Infallible;
 
+/// An [`Includer`] that replaces include blocks with nothing.
 #[derive(Debug)]
 pub struct NullIncluder;
 

src/includes/mod.rs

@@ -20,10 +20,11 @@
 
 //! This module implements "messy includes", or Wikidot native includes.
 //!
-//! It is an annoying but necessary hack that parses the psueodblock
+//! It is an annoying but necessary hack that parses the psuedoblock
 //! `[[include-messy]]` and directly replaces that part with the
 //! foreign page's wikitext.
 
+#[warn(missing_docs)]
 #[cfg(test)]
 mod test;
 
@@ -52,6 +53,8 @@ static INCLUDE_REGEX: Lazy<Regex> = Lazy::new(|| {
 static VARIABLE_REGEX: Lazy<Regex> =
     Lazy::new(|| Regex::new(r"\{\$(?P<name>[a-zA-Z0-9_\-]+)\}").unwrap());
 
+/// Replaces the include blocks in a string with the content of the pages referenced by those
+/// blocks.
 pub fn include<'t, I, E, F>(
     input: &'t str,
     settings: &WikitextSettings,
@@ -85,7 +88,7 @@ where
             mtch.as_str(),
         );
 
-        match parse_include_block(&input[start..], start, settings) {
+        match parse_include_block(input, start, settings) {
             Ok((include, end)) => {
                 ranges.push(start..end);
                 includes.push(include);
@@ -157,6 +160,9 @@ where
     Ok((output, pages))
 }
 
+/// Replaces all specified variables in the content to be included.
+///
+/// Read <https://www.wikidot.com/doc-wiki-syntax:include> for more details.
 fn replace_variables(content: &mut String, variables: &VariableMap) {
     let mut matches = Vec::new();
 

src/includes/parse.rs

@@ -18,6 +18,8 @@
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
+//! This module provides functions to parse strings into [`IncludeRef`]s
+
 use super::IncludeRef;
 use crate::data::{PageRef, PageRefParseError};
 use crate::settings::WikitextSettings;
@@ -30,6 +32,16 @@ use std::collections::HashMap;
 #[grammar = "includes/grammar.pest"]
 struct IncludeParser;
 
+/// Parses a single include block in the text.
+///
+/// # Arguments
+/// The "start" argument is the index at which the include block starts.
+/// It does not necessarily relate to the index of the include within the text str.
+///
+/// # Return values
+/// Returns a tuple of an [`IncludeRef`] that represents the included text and a usize that
+/// represents the end index of the include block, such that start..end covers the full include
+/// block (before the include goes through).
 pub fn parse_include_block<'t>(
     text: &'t str,
     start: usize,
@@ -41,7 +53,7 @@ pub fn parse_include_block<'t>(
         Rule::include_normal
     };
 
-    match IncludeParser::parse(rule, text) {
+    match IncludeParser::parse(rule, &text[start..]) {
         Ok(mut pairs) => {
             // Extract inner pairs
             // These actually make up the include block's tokens
@@ -63,6 +75,7 @@ pub fn parse_include_block<'t>(
     }
 }
 
+/// Creates an [`IncludeRef`] out of pest [`Pairs`].
 fn process_pairs(mut pairs: Pairs<Rule>) -> Result<IncludeRef, IncludeParseError> {
     let page_raw = pairs.next().ok_or(IncludeParseError)?.as_str();
     let page_ref = PageRef::parse(page_raw)?;

src/info.rs

@@ -18,6 +18,8 @@
  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
+//! This module has build and meta information about the library.
+
 #[allow(unused)]
 mod build {
     include!(concat!(env!("OUT_DIR"), "/built.rs"));
@@ -40,7 +42,9 @@ static VERSION_INFO: Lazy<String> = Lazy::new(|| {
 
     version
 });
+/// The package name and version info.
 pub static VERSION: Lazy<String> = Lazy::new(|| format!("{PKG_NAME} {}", *VERSION_INFO));
+/// The full version info, including build information.
 pub static FULL_VERSION: Lazy<String> = Lazy::new(|| {
     let mut version = format!("{}\n\nCompiled:\n", *VERSION_INFO);
 
@@ -51,10 +55,10 @@ pub static FULL_VERSION: Lazy<String> = Lazy::new(|| {
 
     version
 });
-pub static VERSION_WITH_NAME: Lazy<String> =
-    Lazy::new(|| format!("{PKG_NAME} {}", *VERSION));
+/// The package name and full version info, including build information.
 pub static FULL_VERSION_WITH_NAME: Lazy<String> =
     Lazy::new(|| format!("{PKG_NAME} {}", *FULL_VERSION));
+// The last 8 characters of the commit hash for this version.
 pub static GIT_COMMIT_HASH_SHORT: Lazy<Option<&'static str>> =
     Lazy::new(|| GIT_COMMIT_HASH.map(|s| &s[..8]));
 

src/lib.rs

@@ -133,6 +133,7 @@ pub use self::preproc::preprocess;
 pub use self::tokenizer::{tokenize, Tokenization};
 pub use self::utf16::Utf16IndexMap;
 
+/// This module collects commonly used traits from this crate.
 pub mod prelude {
     pub use super::data::{PageInfo, ScoreValue};
     pub use super::includes::{include, Includer};