docs for Source

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);

src/source.rs

@@ -1,44 +1,51 @@
+//! 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,
     path: Option<PathBuf>,
 }
 
 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,
             path: Some(path.as_ref().to_path_buf()),
         })
     }
 
+    /// 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());
     }