📜 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; 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

View File

@@ -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

View File

@@ -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.

View File

@@ -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