📜 Add better documentation across the compiler. #3

Merged
acw merged 19 commits from acw/better-docs into develop 2023-05-13 12:34:48 -07:00
4 changed files with 17 additions and 17 deletions
Showing only changes of commit ec7ad405a8 - Show all commits

View File

@@ -54,7 +54,7 @@ use std::str::FromStr;
use thiserror::Error;
/// 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
/// suggest using the [`From`] implementation to turn this into a [`Diagnostic`],
/// and then printing it via [`codespan_reporting`].
@@ -98,7 +98,7 @@ pub enum ParserError {
impl ParserError {
/// Convert one of lalrpop's parser errors into one of our own, which we can more
/// easily implement translation into [`Diagnostic`].
///
///
/// 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,
/// 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 {
/// 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
/// 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
@@ -245,7 +245,7 @@ impl Program {
}
/// 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
/// report an error, at which point [`codespan_reporting`] may have some nasty things
/// to say to you.
@@ -261,7 +261,7 @@ impl Program {
impl Statement {
/// 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
/// 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

View File

@@ -4,7 +4,7 @@ use crate::syntax::Location;
pub static BINARY_OPERATORS: &[&str] = &["+", "-", "*", "/"];
/// A structure represented a parsed program.
///
///
/// One `Program` is associated with exactly one input file, and the
/// vector is arranged in exactly the same order as the parsed file.
/// Because this is the syntax layer, the program is guaranteed to be
@@ -17,13 +17,13 @@ pub struct Program {
}
/// A parsed statement.
///
///
/// Statements are guaranteed to be syntactically valid, but may be
/// complete nonsense at the semantic level. Which is to say, all the
/// print statements were correctly formatted, and all the variables
/// 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
/// source location; it is testing if the two statements say the same
/// thing, not if they are the exact same statement.
@@ -49,7 +49,7 @@ impl PartialEq for Statement {
}
/// An expression in the underlying syntax.
///
///
/// Like statements, these expressions are guaranteed to have been
/// formatted correctly, but may not actually make any sense. Also
/// like Statements, the [`PartialEq`] implementation does not take

View File

@@ -5,12 +5,12 @@ use crate::syntax::{Expression, Program, Statement};
impl Program {
/// 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
/// 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
/// doing.
///
///
/// 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
/// we don't check for those in the compiled code.

View File

@@ -3,7 +3,7 @@ use codespan_reporting::diagnostic::Diagnostic;
use std::collections::HashMap;
/// An error we found while validating the input program.
///
///
/// These errors indicate that we should stop trying to compile
/// 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
@@ -24,7 +24,7 @@ impl From<Error> for Diagnostic<usize> {
}
/// A problem we found validating the input that isn't critical.
///
///
/// 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
/// these things, if you want to present this information to the user,
@@ -52,10 +52,10 @@ impl From<Warning> for Diagnostic<usize> {
impl Program {
/// Validate that the program makes semantic sense, not just syntactic sense.
///
///
/// This checks for things like references to variables that don't exist, for
/// 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>) {
let mut errors = vec![];
let mut warnings = vec![];
@@ -73,7 +73,7 @@ impl Program {
impl Statement {
/// Validate that the statement makes semantic sense, not just syntactic sense.
///
///
/// This checks for things like references to variables that don't exist, for
/// example, and generates warnings for things that are inadvisable but not
/// actually a problem. Since statements appear in a broader context, you'll