From cccbe7a325887107c0b180735eb333fa8d4b5847 Mon Sep 17 00:00:00 2001 From: Jeff Date: Thu, 8 Aug 2024 21:59:09 -0400 Subject: [PATCH] Write docs --- dust-lang/src/abstract_tree.rs | 2 ++ dust-lang/src/built_in_function.rs | 2 ++ dust-lang/src/dust_error.rs | 5 +++-- dust-lang/src/identifier.rs | 2 ++ dust-lang/src/parse.rs | 10 +++++----- dust-lang/src/token.rs | 1 + dust-lang/src/type.rs | 24 +++++++++++------------- dust-lang/src/value.rs | 2 +- dust-lang/src/vm.rs | 1 + 9 files changed, 28 insertions(+), 21 deletions(-) diff --git a/dust-lang/src/abstract_tree.rs b/dust-lang/src/abstract_tree.rs index 8888cbe..7eefe80 100644 --- a/dust-lang/src/abstract_tree.rs +++ b/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, diff --git a/dust-lang/src/built_in_function.rs b/dust-lang/src/built_in_function.rs index 6c47a9f..fb21fca 100644 --- a/dust-lang/src/built_in_function.rs +++ b/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 diff --git a/dust-lang/src/dust_error.rs b/dust-lang/src/dust_error.rs index b435e4d..7a942d2 100644 --- a/dust-lang/src/dust_error.rs +++ b/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)) diff --git a/dust-lang/src/identifier.rs b/dust-lang/src/identifier.rs index ebcc8cd..42f874b 100644 --- a/dust-lang/src/identifier.rs +++ b/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> { 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); diff --git a/dust-lang/src/parse.rs b/dust-lang/src/parse.rs index d204179..d2c28ff 100644 --- a/dust-lang/src/parse.rs +++ b/dust-lang/src/parse.rs @@ -1,8 +1,8 @@ -/// Parsing tools. -/// -/// This module provides two parsing options: -/// - `parse` convenience function -/// - `Parser` struct, which parses the input a statement at a time +//! Parsing tools. +//! +//! This module provides two parsing options: +//! - `parse` convenience function +//! - `Parser` struct, which parses the input a statement at a time use std::{ collections::VecDeque, error::Error, diff --git a/dust-lang/src/token.rs b/dust-lang/src/token.rs index 8632458..50239d6 100644 --- a/dust-lang/src/token.rs +++ b/dust-lang/src/token.rs @@ -1,3 +1,4 @@ +//! Token and TokenOwned types. use std::fmt::{self, Display, Formatter}; use serde::{Deserialize, Serialize}; diff --git a/dust-lang/src/type.rs b/dust-lang/src/type.rs index bbc811c..8ffd7ac 100644 --- a/dust-lang/src/type.rs +++ b/dust-lang/src/type.rs @@ -1,16 +1,14 @@ -/** -Description of a kind of value. - -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 -interpreter should use the validation phase to enforce that all Generic types have a concrete -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 -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))`. -**/ +/// Description of a kind of value. +/// +/// 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 +/// interpreter should use the analysis phase to enforce that all Generic types have a concrete +/// 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 +/// 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))`. use std::{ collections::BTreeMap, fmt::{self, Display, Formatter}, diff --git a/dust-lang/src/value.rs b/dust-lang/src/value.rs index df21272..1fea438 100644 --- a/dust-lang/src/value.rs +++ b/dust-lang/src/value.rs @@ -1,4 +1,4 @@ -/// Dust value representation +//! Dust value representation use std::{ cmp::Ordering, collections::{BTreeMap, HashMap}, diff --git a/dust-lang/src/vm.rs b/dust-lang/src/vm.rs index 45dcacc..c9f51aa 100644 --- a/dust-lang/src/vm.rs +++ b/dust-lang/src/vm.rs @@ -1,3 +1,4 @@ +//! Virtual machine for running the abstract syntax tree. use std::{ collections::HashMap, error::Error,