Add documentation

Author: lrossi

src/compiler.rs

@@ -4,10 +4,16 @@
 use crate::{emitter::Emitter, parser::Parser, wat::Wat, Error, ErrorKind, Severity};
 use alloc::{string::String, vec::Vec};
 
+/// Public interface to the C-to-WebAssembly compiler.
+///
+/// Same instance can be reused to compile multiple files.
 #[derive(Copy, Clone, Eq, PartialEq, Debug, Default)]
 pub struct Compiler;
 
 impl Compiler {
+    /// Compiles the given C source to [WAT (WebAssembly Text) format](https://webassembly.github.io/mutable-global/core/text/index.html).
+    ///
+    /// Call [Self::assemble] to produce a binary from the resulting WAT.
     pub fn compile(&mut self, source: impl AsRef<str>) -> Result<String, Error> {
         let mut parser = Parser::new(source.as_ref());
         let ast = parser.parse()?;
@@ -16,6 +22,9 @@ impl Compiler {
         Ok(wat)
     }
 
+    /// Compiles the given WAT source to [WebAssembly Binary format](https://webassembly.github.io/mutable-global/core/binary/index.html).
+    ///
+    /// Call [Self::compile] to obtain a WAT source from the C source.
     #[cfg(feature = "binary-output")]
     pub fn assemble(&mut self, source: impl AsRef<str>) -> Result<Vec<u8>, Error> {
         use alloc::string::ToString;

src/error.rs

@@ -5,62 +5,104 @@ use crate::token::TokenKind;
 use alloc::{rc::Rc, string::String};
 use core::fmt::{self, Display, Formatter, Result};
 
+/// Kind of error encountered during compilation.
 #[derive(Clone, Eq, PartialEq, Hash, Debug)]
 pub enum Kind {
+    /// Invalid token, with the given offending character.
     InvalidToken(char),
+    /// Invalid constant value.
     InvalidConstant,
+    /// Constant value exceeded the capacity of a 32-bit `int`.
     ConstantTooLarge,
+    /// Unknown type encountered, with the given token.
     UnknownType(TokenKind),
+    /// Expected a type but none was found.
     ExpectedType,
+    /// Expected an identifier but the given token was found instead (or `None` on EOF).
     ExpectedIdentifier(Option<TokenKind>),
+    /// Expected a specific token but another given token was found instead (or `None` on EOF).
     ExpectedToken(TokenKind, Option<TokenKind>),
+    /// Expected an expression but the given token was found instead (or `None` on EOF).
     ExpectedExpression(Option<TokenKind>),
+    /// Encountered a redefinition of an identifier.
     Redefinition(Rc<String>),
+    /// Attempted to use an undeclared identifier.
     Undeclared(Rc<String>),
+    /// Conflicting type definitions for the same identifier.
     ConflictingTypes(Rc<String>),
+    /// Invalid left-hand value in an assignment.
     InvalidLvalue,
+    /// `break` outside of a loop or `switch` statement.
     BreakOutsideLoopOrSwitch,
+    /// `continue` outside of a loop.
     ContinueOutsideLoop,
+    /// Attempted to call an undefined function.
     UndefinedFunction(Rc<String>),
+    /// Expression expected to be constant but wasn't.
     NonConstantExpression,
+    /// Expression expected to be an integer but wasn't.
     NonIntegerExpression,
+    /// Attempted to assign to a `const` variable.
     CannotAssignToConst(Rc<String>),
+    /// Duplicate `case` value in a `switch` statement.
     DuplicateCase,
+    /// Invalid preprocessor directive.
     InvalidDirective(Rc<String>),
+    /// String literal was not properly terminated.
     UnterminatedString,
+    /// Invalid character.
     InvalidCharacter(char),
+    /// Invalid escape sequence in a string literal.
     InvalidEscapeSequence,
+    /// Expected a string literal but the given token was found instead (or `None` on EOF).
     ExpectedString(Option<TokenKind>),
+    /// Error emitted by the [`wat`](https://crates.io/crates/wat) crate when compiling the WAT source to binary.
+    ///
+    /// Note: Likely indicates a bug in this compiler!
     AssemblerError(String),
 }
 
+/// Severity level of an error.
 #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug)]
 pub enum Severity {
+    /// A warning that does not halt compilation.
+    ///
+    /// Note: currently, no warnings are emitted.
     Warning,
+    /// An error that halts compilation.
     Error,
 }
 
+/// Compilation error or warning, including its location and context.
 #[derive(Clone, Eq, PartialEq, Hash, Debug)]
 pub struct Error {
+    /// The line number in the C source where the error occurred.
     pub(crate) line_number: usize,
+    /// The column number in the C source where the error occurred.
     pub(crate) column: usize,
+    /// The kind of error encountered.
     pub(crate) kind: Kind,
+    /// The severity of the error.
     pub(crate) severity: Severity,
 }
 
 impl Error {
+    /// Returns the line number in the C source where the error occurred.
     pub fn line_number(&self) -> usize {
         self.line_number
     }
 
+    /// Returns the column number in the C source where the error occurred.
     pub fn column(&self) -> usize {
         self.column
     }
 
+    /// Returns the error kind.
     pub fn kind(&self) -> &Kind {
         &self.kind
     }
 
+    /// Returns the error severity level.
     pub fn severity(&self) -> Severity {
         self.severity
     }

src/lib.rs

@@ -2,6 +2,8 @@
 // SPDX-License-Identifier: MPL-2.0
 
 #![no_std]
+#![warn(missing_docs)]
+#![doc = include_str!("../README.md")]
 
 #[macro_use]
 extern crate alloc;