Document everything 📜

1 files changed, 25 insertions, 9 deletions

diff --git a/src/syntax/span.rs b/src/syntax/span.rs
index f5bd4caf..ad1358cf 100644
--- a/src/syntax/span.rs
+++ b/src/syntax/span.rs
@@ -5,18 +5,20 @@ use std::ops::{Add, Sub};
 use serde::Serialize;
 
 
-/// A line-column position in source code.
+/// Zero-indexed line-column position in source code.
 #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Serialize)]
 pub struct Position {
-    /// The 0-indexed line (inclusive).
+    /// The zero-indexed line.
     pub line: usize,
-    /// The 0-indexed column (inclusive).
+    /// The zero-indexed column.
     pub column: usize,
 }
 
 impl Position {
+    /// The line 0, column 0 position.
     pub const ZERO: Position = Position { line: 0, column: 0 };
 
+    /// Crete a new instance from line and column.
     pub fn new(line: usize, column: usize) -> Position {
         Position { line, column }
     }
@@ -58,20 +60,25 @@ impl Sub for Position {
     }
 }
 
-/// Describes a slice of source code.
+/// Locates a slice of source code.
 #[derive(Copy, Clone, Eq, PartialEq, Hash, Serialize)]
 pub struct Span {
+    /// The inclusive start position.
     pub start: Position,
+    /// The inclusive end position.
     pub end: Position,
 }
 
 impl Span {
+    /// A dummy span.
     pub const ZERO: Span = Span { start: Position::ZERO, end: Position::ZERO };
 
+    /// Create a new span from start and end positions.
     pub fn new(start: Position, end: Position) -> Span {
         Span { start, end }
     }
 
+    /// Create a new span with the earlier start and later end position.
     pub fn merge(a: Span, b: Span) -> Span {
         Span {
             start: a.start.min(b.start),
@@ -79,14 +86,15 @@ impl Span {
         }
     }
 
+    /// Create a span including just a single position.
     pub fn at(pos: Position) -> Span {
         Span { start: pos, end: pos }
     }
 
-    pub fn expand(&mut self, other: Span) {
-        *self = Span::merge(*self, other)
-    }
-
+    /// Offset a span by a start position.
+    ///
+    /// This is, for example, used to translate error spans from function local
+    /// to global.
     pub fn offset(self, start: Position) -> Span {
         Span {
             start: start + self.start,
@@ -95,26 +103,32 @@ impl Span {
     }
 }
 
-/// Annotates a value with the part of the source code it corresponds to.
+/// A value with the span it corresponds to in the source code.
 #[derive(Copy, Clone, Eq, PartialEq, Hash, Serialize)]
 pub struct Spanned<T> {
+    /// The value.
     pub v: T,
+    /// The corresponding span.
     pub span: Span,
 }
 
 impl<T> Spanned<T> {
+    /// Create a new instance from a value and its span.
     pub fn new(v: T, span: Span) -> Spanned<T> {
         Spanned { v, span }
     }
 
+    /// Access the value.
     pub fn value(self) -> T {
         self.v
     }
 
+    /// Map the value using a function while keeping the span.
     pub fn map<V, F>(self, f: F) -> Spanned<V> where F: FnOnce(T) -> V {
         Spanned { v: f(self.v), span: self.span }
     }
 
+    /// Maps the span while keeping the value.
     pub fn map_span<F>(mut self, f: F) -> Spanned<T> where F: FnOnce(Span) -> Span {
         self.span = f(self.span);
         self
@@ -124,6 +138,8 @@ impl<T> Spanned<T> {
 /// A vector of spanned things.
 pub type SpanVec<T> = Vec<Spanned<T>>;
 
+/// [Offset](Span::offset) all spans in a vector of spanned things by a start
+/// position.
 pub fn offset_spans<T>(vec: SpanVec<T>, start: Position) -> impl Iterator<Item=Spanned<T>> {
     vec.into_iter().map(move |s| s.map_span(|span| span.offset(start)))
 }