From 4a0d6cf0e323b3b38548d1500d066648b49ca465 Mon Sep 17 00:00:00 2001
From: Sam Johnson <sam@durosoft.com>
Date: Fri, 29 Mar 2024 14:27:28 -0400
Subject: [PATCH] docs for Source

---
 src/parsable/numbers.rs |  6 +++---
 src/source.rs           | 25 ++++++++++++++++---------
 2 files changed, 19 insertions(+), 12 deletions(-)

diff --git a/src/parsable/numbers.rs b/src/parsable/numbers.rs
index df8181e..903321f 100644
--- a/src/parsable/numbers.rs
+++ b/src/parsable/numbers.rs
@@ -275,7 +275,7 @@ impl From<rust_decimal::Decimal> for Decimal {
     fn from(value: rust_decimal::Decimal) -> Self {
         let st = value.to_string();
         let len = st.len();
-        let span = Span::new(Rc::new(Source::from_string(st)), 0..len);
+        let span = Span::new(Rc::new(Source::from_str(st)), 0..len);
         Decimal(value, span.into())
     }
 }
@@ -319,9 +319,9 @@ impl Parsable for Decimal {
     }
 }
 
-/// A bounded version of [`Int64`].
+/// A bounded version of [`I64`].
 ///
-/// Bounds are _inclusive_, so [`BoundedInt64<3, 7>`] means only 3, 4, 5, 6, and 7 are allowed
+/// Bounds are _inclusive_, so [`BoundedI64<3, 7>`] means only 3, 4, 5, 6, and 7 are allowed
 /// as values.
 #[derive(ParsableExt, Clone, PartialEq, Eq, Hash, Debug)]
 pub struct BoundedI64<const MIN: i64, const MAX: i64>(I64);
diff --git a/src/source.rs b/src/source.rs
index 28f2eb7..61cb879 100644
--- a/src/source.rs
+++ b/src/source.rs
@@ -1,8 +1,14 @@
+//! home of [`Source`] and related types.
+
+#[cfg(doc)]
+use super::*;
+
 use std::{
     ops::Deref,
     path::{Path, PathBuf},
 };
 
+/// Represents source text that can be indexed into to define individual [`Span`]s.
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
 pub struct Source {
     text: String,
@@ -10,28 +16,28 @@ pub struct Source {
 }
 
 impl Source {
+    /// Returns the underlying text of this [`Source`], with original formatting.
     pub fn source_text(&self) -> &str {
         &self.text
     }
 
+    /// Returns the path of the file that this [`Source`] was read from, if it was read from a file.
     pub fn source_path(&self) -> Option<&Path> {
         self.path.as_ref().map(|path| path.as_path())
     }
 
-    pub fn from_string(string: String) -> Self {
-        Source {
-            text: string,
-            path: None,
-        }
-    }
-
-    pub fn from_str(string: impl AsRef<str>) -> Self {
+    /// Returns the length of the underlying text of this [`Source`].
+    pub fn from_str(string: impl Into<String>) -> Self {
         Source {
-            text: string.as_ref().to_string(),
+            text: string.into(),
             path: None,
         }
     }
 
+    /// Reads the contents of a file and returns a [`Source`] with the file's text.
+    ///
+    /// Since no parsing is done at this stage, only IO or encoding errors will be returned,
+    /// regardless of the validity of the syntax in the file.
     pub fn from_file(path: impl AsRef<Path>) -> Result<Self, std::io::Error> {
         std::fs::read_to_string(path.as_ref()).map(|text| Source {
             text,
@@ -39,6 +45,7 @@ impl Source {
         })
     }
 
+    /// Sets the path of the file that this [`Source`] was read from.
     pub fn set_path(&mut self, path: Option<impl AsRef<Path>>) {
         self.path = path.map(|p| p.as_ref().to_path_buf());
     }