📜 Add better documentation across the compiler. #3
@@ -54,7 +54,7 @@ use std::str::FromStr;
|
|||||||
use thiserror::Error;
|
use thiserror::Error;
|
||||||
|
|
||||||
/// One of the many errors that can occur when processing text input.
|
/// One of the many errors that can occur when processing text input.
|
||||||
///
|
///
|
||||||
/// If you get one of these and want to display it to the user, we strongly
|
/// If you get one of these and want to display it to the user, we strongly
|
||||||
/// suggest using the [`From`] implementation to turn this into a [`Diagnostic`],
|
/// suggest using the [`From`] implementation to turn this into a [`Diagnostic`],
|
||||||
/// and then printing it via [`codespan_reporting`].
|
/// and then printing it via [`codespan_reporting`].
|
||||||
@@ -98,7 +98,7 @@ pub enum ParserError {
|
|||||||
impl ParserError {
|
impl ParserError {
|
||||||
/// Convert one of lalrpop's parser errors into one of our own, which we can more
|
/// Convert one of lalrpop's parser errors into one of our own, which we can more
|
||||||
/// easily implement translation into [`Diagnostic`].
|
/// easily implement translation into [`Diagnostic`].
|
||||||
///
|
///
|
||||||
/// This function is relatively straightforward, because we match the errors pretty
|
/// This function is relatively straightforward, because we match the errors pretty
|
||||||
/// closely. The major thing we do here is convert [`lalrpop`]'s notion of a location,
|
/// closely. The major thing we do here is convert [`lalrpop`]'s notion of a location,
|
||||||
/// which is just an offset that it got from the lexer, into an actual location that
|
/// which is just an offset that it got from the lexer, into an actual location that
|
||||||
@@ -227,7 +227,7 @@ impl<'a> From<&'a ParserError> for Diagnostic<usize> {
|
|||||||
|
|
||||||
impl Program {
|
impl Program {
|
||||||
/// Parse the given file, adding it to the database as part of the process.
|
/// Parse the given file, adding it to the database as part of the process.
|
||||||
///
|
///
|
||||||
/// This operation reads the file from disk and adds it to the database for future
|
/// This operation reads the file from disk and adds it to the database for future
|
||||||
/// reference. If you get an error, we strongly suggest conversion to [`Diagnostic`]
|
/// reference. If you get an error, we strongly suggest conversion to [`Diagnostic`]
|
||||||
/// and then reporting it to the user via [`codespan_reporting`]. You should use
|
/// and then reporting it to the user via [`codespan_reporting`]. You should use
|
||||||
@@ -245,7 +245,7 @@ impl Program {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/// Parse a block of text you have in memory, using the given index for [`Location`]s.
|
/// Parse a block of text you have in memory, using the given index for [`Location`]s.
|
||||||
///
|
///
|
||||||
/// If you use a nonsensical file index, everything will work fine until you try to
|
/// If you use a nonsensical file index, everything will work fine until you try to
|
||||||
/// report an error, at which point [`codespan_reporting`] may have some nasty things
|
/// report an error, at which point [`codespan_reporting`] may have some nasty things
|
||||||
/// to say to you.
|
/// to say to you.
|
||||||
@@ -261,7 +261,7 @@ impl Program {
|
|||||||
|
|
||||||
impl Statement {
|
impl Statement {
|
||||||
/// Parse a statement that you have in memory, using the given index for [`Location`]s.
|
/// Parse a statement that you have in memory, using the given index for [`Location`]s.
|
||||||
///
|
///
|
||||||
/// As with [`Program::parse`], if you use a bad file index, you'll get weird behaviors
|
/// As with [`Program::parse`], if you use a bad file index, you'll get weird behaviors
|
||||||
/// when you try to print errors, but things should otherwise work fine. This function
|
/// when you try to print errors, but things should otherwise work fine. This function
|
||||||
/// will only parse a single statement, which is useful in the REPL, but probably shouldn't
|
/// will only parse a single statement, which is useful in the REPL, but probably shouldn't
|
||||||
|
|||||||
@@ -4,7 +4,7 @@ use crate::syntax::Location;
|
|||||||
pub static BINARY_OPERATORS: &[&str] = &["+", "-", "*", "/"];
|
pub static BINARY_OPERATORS: &[&str] = &["+", "-", "*", "/"];
|
||||||
|
|
||||||
/// A structure represented a parsed program.
|
/// A structure represented a parsed program.
|
||||||
///
|
///
|
||||||
/// One `Program` is associated with exactly one input file, and the
|
/// One `Program` is associated with exactly one input file, and the
|
||||||
/// vector is arranged in exactly the same order as the parsed file.
|
/// vector is arranged in exactly the same order as the parsed file.
|
||||||
/// Because this is the syntax layer, the program is guaranteed to be
|
/// Because this is the syntax layer, the program is guaranteed to be
|
||||||
@@ -17,13 +17,13 @@ pub struct Program {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/// A parsed statement.
|
/// A parsed statement.
|
||||||
///
|
///
|
||||||
/// Statements are guaranteed to be syntactically valid, but may be
|
/// Statements are guaranteed to be syntactically valid, but may be
|
||||||
/// complete nonsense at the semantic level. Which is to say, all the
|
/// complete nonsense at the semantic level. Which is to say, all the
|
||||||
/// print statements were correctly formatted, and all the variables
|
/// print statements were correctly formatted, and all the variables
|
||||||
/// referenced are definitely valid symbols, but they may not have
|
/// referenced are definitely valid symbols, but they may not have
|
||||||
/// been defined or anything.
|
/// been defined or anything.
|
||||||
///
|
///
|
||||||
/// Note that equivalence testing on statements is independent of
|
/// Note that equivalence testing on statements is independent of
|
||||||
/// source location; it is testing if the two statements say the same
|
/// source location; it is testing if the two statements say the same
|
||||||
/// thing, not if they are the exact same statement.
|
/// thing, not if they are the exact same statement.
|
||||||
@@ -49,7 +49,7 @@ impl PartialEq for Statement {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/// An expression in the underlying syntax.
|
/// An expression in the underlying syntax.
|
||||||
///
|
///
|
||||||
/// Like statements, these expressions are guaranteed to have been
|
/// Like statements, these expressions are guaranteed to have been
|
||||||
/// formatted correctly, but may not actually make any sense. Also
|
/// formatted correctly, but may not actually make any sense. Also
|
||||||
/// like Statements, the [`PartialEq`] implementation does not take
|
/// like Statements, the [`PartialEq`] implementation does not take
|
||||||
|
|||||||
@@ -5,12 +5,12 @@ use crate::syntax::{Expression, Program, Statement};
|
|||||||
|
|
||||||
impl Program {
|
impl Program {
|
||||||
/// Evaluate the program, returning either an error or what it prints out when run.
|
/// Evaluate the program, returning either an error or what it prints out when run.
|
||||||
///
|
///
|
||||||
/// Doing this evaluation is particularly useful for testing, to ensure that if we
|
/// Doing this evaluation is particularly useful for testing, to ensure that if we
|
||||||
/// modify a program in some way it does the same thing on both sides of the
|
/// modify a program in some way it does the same thing on both sides of the
|
||||||
/// transformation. It's also sometimes just nice to know what a program will be
|
/// transformation. It's also sometimes just nice to know what a program will be
|
||||||
/// doing.
|
/// doing.
|
||||||
///
|
///
|
||||||
/// Note that the errors here are slightly more strict that we enforce at runtime.
|
/// Note that the errors here are slightly more strict that we enforce at runtime.
|
||||||
/// For example, we check for overflow and underflow errors during evaluation, and
|
/// For example, we check for overflow and underflow errors during evaluation, and
|
||||||
/// we don't check for those in the compiled code.
|
/// we don't check for those in the compiled code.
|
||||||
|
|||||||
@@ -3,7 +3,7 @@ use codespan_reporting::diagnostic::Diagnostic;
|
|||||||
use std::collections::HashMap;
|
use std::collections::HashMap;
|
||||||
|
|
||||||
/// An error we found while validating the input program.
|
/// An error we found while validating the input program.
|
||||||
///
|
///
|
||||||
/// These errors indicate that we should stop trying to compile
|
/// These errors indicate that we should stop trying to compile
|
||||||
/// the program, because it's just fundamentally broken in a way
|
/// the program, because it's just fundamentally broken in a way
|
||||||
/// that we're not going to be able to work through. As with most
|
/// that we're not going to be able to work through. As with most
|
||||||
@@ -24,7 +24,7 @@ impl From<Error> for Diagnostic<usize> {
|
|||||||
}
|
}
|
||||||
|
|
||||||
/// A problem we found validating the input that isn't critical.
|
/// A problem we found validating the input that isn't critical.
|
||||||
///
|
///
|
||||||
/// These are things that the user might want to do something about,
|
/// These are things that the user might want to do something about,
|
||||||
/// but we can keep going without it being a problem. As with most of
|
/// but we can keep going without it being a problem. As with most of
|
||||||
/// these things, if you want to present this information to the user,
|
/// these things, if you want to present this information to the user,
|
||||||
@@ -52,10 +52,10 @@ impl From<Warning> for Diagnostic<usize> {
|
|||||||
|
|
||||||
impl Program {
|
impl Program {
|
||||||
/// Validate that the program makes semantic sense, not just syntactic sense.
|
/// Validate that the program makes semantic sense, not just syntactic sense.
|
||||||
///
|
///
|
||||||
/// This checks for things like references to variables that don't exist, for
|
/// This checks for things like references to variables that don't exist, for
|
||||||
/// example, and generates warnings for things that are inadvisable but not
|
/// example, and generates warnings for things that are inadvisable but not
|
||||||
/// actually a problem.
|
/// actually a problem.
|
||||||
pub fn validate(&self) -> (Vec<Error>, Vec<Warning>) {
|
pub fn validate(&self) -> (Vec<Error>, Vec<Warning>) {
|
||||||
let mut errors = vec![];
|
let mut errors = vec![];
|
||||||
let mut warnings = vec![];
|
let mut warnings = vec![];
|
||||||
@@ -73,7 +73,7 @@ impl Program {
|
|||||||
|
|
||||||
impl Statement {
|
impl Statement {
|
||||||
/// Validate that the statement makes semantic sense, not just syntactic sense.
|
/// Validate that the statement makes semantic sense, not just syntactic sense.
|
||||||
///
|
///
|
||||||
/// This checks for things like references to variables that don't exist, for
|
/// This checks for things like references to variables that don't exist, for
|
||||||
/// example, and generates warnings for things that are inadvisable but not
|
/// example, and generates warnings for things that are inadvisable but not
|
||||||
/// actually a problem. Since statements appear in a broader context, you'll
|
/// actually a problem. Since statements appear in a broader context, you'll
|
||||||
|
|||||||
Reference in New Issue
Block a user