Write docs

dust-lang/src/abstract_tree.rs

@@ -1,3 +1,4 @@
+//! In-memory representation of a Dust program.
 use std::{
     collections::{HashMap, VecDeque},
     fmt::{self, Display, Formatter},
@@ -7,6 +8,7 @@ use serde::{Deserialize, Serialize};
 
 use crate::{BuiltInFunction, Identifier, Span, Type, Value};
 
+/// In-memory representation of a Dust program.
 #[derive(Debug, Clone, Eq, PartialEq, PartialOrd, Ord, Serialize, Deserialize)]
 pub struct AbstractSyntaxTree {
     pub nodes: VecDeque<Node>,

dust-lang/src/built_in_function.rs

@@ -1,3 +1,4 @@
+//! Integrated functions that can be called from Dust code.
 use std::{
     error::Error,
     fmt::{self, Display, Formatter},
@@ -8,6 +9,7 @@ use serde::{Deserialize, Serialize};
 
 use crate::{Type, Value};
 
+/// Integrated function that can be called from Dust code.
 #[derive(Debug, Clone, Eq, PartialEq, PartialOrd, Ord, Serialize, Deserialize)]
 pub enum BuiltInFunction {
     // Integer and float tools

dust-lang/src/dust_error.rs

@@ -1,8 +1,11 @@
+//! Top-level error handling for the Dust language.
 use annotate_snippets::{Level, Renderer, Snippet};
 use std::{error::Error, fmt::Display};
 
 use crate::{AnalyzerError, VmError};
 
+/// An error that occurred during the execution of the Dust language and its
+/// corresponding source code.
 #[derive(Debug, Clone, PartialEq)]
 pub struct DustError<'src> {
     vm_error: VmError,
@@ -43,11 +46,9 @@ impl<'src> DustError<'src> {
             VmError::ExpectedValue { position } => position,
         };
         let label = self.vm_error.to_string();
-
         let message = Level::Error.title(title).snippet(
             Snippet::source(self.source).annotation(Level::Info.span(span.0..span.1).label(&label)),
         );
-
         let renderer = Renderer::styled();
 
         format!("{}", renderer.render(message))

dust-lang/src/identifier.rs

@@ -1,3 +1,4 @@
+//! Key used to identify a value or type.
 use std::{
     collections::HashSet,
     fmt::{self, Display, Formatter},
@@ -13,6 +14,7 @@ fn identifier_cache<'a>() -> &'a RwLock<HashSet<Identifier>> {
     IDENTIFIER_CACHE.get_or_init(|| RwLock::new(HashSet::new()))
 }
 
+/// Key used to identify a value or type.
 #[derive(Clone, Debug, Eq, PartialEq, PartialOrd, Ord, Hash)]
 pub struct Identifier(Arc<String>);
 

dust-lang/src/parse.rs

@@ -1,8 +1,8 @@
-/// Parsing tools.
+//! Parsing tools.
-///
+//!
-/// This module provides two parsing options:
+//! This module provides two parsing options:
-/// - `parse` convenience function
+//! - `parse` convenience function
-/// - `Parser` struct, which parses the input a statement at a time
+//! - `Parser` struct, which parses the input a statement at a time
 use std::{
     collections::VecDeque,
     error::Error,

dust-lang/src/token.rs

@@ -1,3 +1,4 @@
+//! Token and TokenOwned types.
 use std::fmt::{self, Display, Formatter};
 
 use serde::{Deserialize, Serialize};

dust-lang/src/type.rs

@@ -1,16 +1,14 @@
-/**
+/// Description of a kind of value.
-Description of a kind of value.
+///
-
+/// Most types are concrete and specific, the exceptions are the Generic and Any types.
-Most types are concrete and specific, the exceptions are the Generic and Any types.
+///
-
+/// Generic types are temporary placeholders that describe a type that will be defined later. The
-Generic types are temporary placeholders that describe a type that will be defined later. The
+/// interpreter should use the analysis phase to enforce that all Generic types have a concrete
-interpreter should use the validation phase to enforce that all Generic types have a concrete
+/// type assigned to them before the program is run.
-type assigned to them before the program is run.
+///
-
+/// The Any type is used in cases where a value's type does not matter. For example, the standard
-The Any type is used in cases where a value's type does not matter. For example, the standard
+/// library's "length" function does not care about the type of item in the list, only the list
-library's "length" function does not care about the type of item in the list, only the list
+/// itself. So the input is defined as `[any]`, i.e. `Type::ListOf(Box::new(Type::Any))`.
-itself. So the input is defined as `[any]`, i.e. `Type::ListOf(Box::new(Type::Any))`.
-**/
 use std::{
     collections::BTreeMap,
     fmt::{self, Display, Formatter},

dust-lang/src/value.rs

@@ -1,4 +1,4 @@
-/// Dust value representation
+//! Dust value representation
 use std::{
     cmp::Ordering,
     collections::{BTreeMap, HashMap},

dust-lang/src/vm.rs

@@ -1,3 +1,4 @@
+//! Virtual machine for running the abstract syntax tree.
 use std::{
     collections::HashMap,
     error::Error,