Added Docstrings (FuelLabs#453)

mitchmindtree · Dec 11, 2021 · dde7293 · dde7293
1 parent e77027e
commit dde7293
Show file tree

Hide file tree

Showing 7 changed files with 86 additions and 10 deletions.
diff --git a/core_lang/src/asm_generation/mod.rs b/core_lang/src/asm_generation/mod.rs
@@ -1276,12 +1276,19 @@ fn add_module_constant_decls<'sc>(
     ok((), warnings, errors)
 }
 
+/// The function selector value and corresponding label.
+type JumpDestination = Vec<([u8; 4], Label)>;
+/// A vector of opcodes representing the body of a contract ABI function.
+type AbiFunctionOpcodeBuffer<'sc> = Vec<Op<'sc>>;
+/// The function selector information and compiled body of a contract ABI function.
+type SerializedAbiFunction<'sc> = (JumpDestination, AbiFunctionOpcodeBuffer<'sc>);
+
 /// Given a contract's abi entries, compile them to jump destinations and an opcode buffer.
 fn compile_contract_to_selectors<'sc>(
     abi_entries: Vec<TypedFunctionDeclaration<'sc>>,
     namespace: &mut AsmNamespace<'sc>,
     register_sequencer: &mut RegisterSequencer,
-) -> CompileResult<'sc, (Vec<([u8; 4], Label)>, Vec<Op<'sc>>)> {
+) -> CompileResult<'sc, SerializedAbiFunction<'sc>> {
     let mut warnings = vec![];
     let mut errors = vec![];
     // for every ABI function, we need:

diff --git a/core_lang/src/constants.rs b/core_lang/src/constants.rs
@@ -1,3 +1,8 @@
+//! Configurable yet nonchanging constants for the compiler.
+
+/// The default extension of [LANGUAGE_NAME] files, e.g. `main.sw`.
 pub const DEFAULT_FILE_EXTENSION: &str = "sw";
+/// After a large language name change PR, we decided to make this configurable. :)
 pub const LANGUAGE_NAME: &str = "Sway";
+/// The size, in bytes, of a single word in the FuelVM.
 pub const VM_WORD_SIZE: u64 = 8;
diff --git a/core_lang/src/error.rs b/core_lang/src/error.rs
@@ -1,3 +1,5 @@
+//! Tools related to handling/recovering from Sway compile errors and reporting them to the user.
+
 use crate::parser::Rule;
 use crate::span::Span;
 use crate::style::{to_screaming_snake_case, to_snake_case, to_upper_camel_case};

diff --git a/core_lang/src/lib.rs b/core_lang/src/lib.rs
@@ -40,65 +40,109 @@ pub use ident::Ident;
 pub use semantic_analysis::{Namespace, TypedDeclaration, TypedFunctionDeclaration};
 pub use type_engine::TypeInfo;
 
-// todo rename to language name
+/// Represents a parsed, but not yet type-checked, Sway program.
+/// A Sway program can be either a contract, script, predicate, or
+/// it can be a library to be imported into one of the aforementioned
+/// program types.
 #[derive(Debug)]
 pub struct HllParseTree<'sc> {
     pub tree_type: TreeType<'sc>,
     pub tree: ParseTree<'sc>,
 }
 
+/// Represents some exportable information that results from compiling some
+/// Sway source code.
 #[derive(Debug)]
 pub struct HllTypedParseTree<'sc> {
     pub library_exports: LibraryExports<'sc>,
 }
 
+/// Represents some exportable information that results from compiling some
+/// Sway source code.
 #[derive(Debug)]
 pub struct LibraryExports<'sc> {
     pub namespace: Namespace<'sc>,
     trees: Vec<TypedParseTree<'sc>>,
 }
 
+/// Represents a parsed (but not yet type checked) Sway syntax tree.
 #[derive(Debug)]
 pub struct ParseTree<'sc> {
-    /// In a typical programming language, you might have a single root node for your syntax tree.
-    /// In this language however, we want to expose multiple public functions at the root
-    /// level so the tree is multi-root.
+    /// The untyped AST nodes that constitute this tree's root nodes.
     pub root_nodes: Vec<AstNode<'sc>>,
+    /// The [span::Span] of the entire tree.
     pub span: span::Span<'sc>,
 }
 
+/// A single [AstNode] represents a node in the parse tree. Note that [AstNode]
+/// is a recursive type and can contain other [AstNode], thus populating the tree.
 #[derive(Debug, Clone)]
 pub struct AstNode<'sc> {
+    /// The content of this ast node, which could be any control flow structure or other
+    /// basic organizational component.
     pub content: AstNodeContent<'sc>,
+    /// The [span::Span] representing this entire [AstNode].
     pub span: span::Span<'sc>,
 }
 
+/// Represents the various structures that constitute a Sway program.
 #[derive(Debug, Clone)]
 pub enum AstNodeContent<'sc> {
+    /// A statement of the form `use foo::bar;` or `use ::foo::bar;`
     UseStatement(UseStatement<'sc>),
+    /// A statement of the form `return foo;`
     ReturnStatement(ReturnStatement<'sc>),
+    /// Any type of declaration, of which there are quite a few. See [Declaration] for more details
+    /// on the possible variants.
     Declaration(Declaration<'sc>),
+    /// Any type of expression, of which there are quite a few. See [Expression] for more details.
     Expression(Expression<'sc>),
+    /// An implicit return expression is different from a [AstNodeContent::ReturnStatement] because
+    /// it is not a control flow item. Therefore it is a different variant.
+    ///
+    /// An implicit return expression is an [Expression] at the end of a code block which has no
+    /// semicolon, denoting that it is the [Expression] to be returned from that block.
     ImplicitReturnExpression(Expression<'sc>),
+    /// A control flow element which loops continually until some boolean expression evaluates as
+    /// `false`.
     WhileLoop(WhileLoop<'sc>),
+    /// A statement of the form `dep foo::bar;` which imports/includes another source file.
     IncludeStatement(IncludeStatement<'sc>),
 }
 
 impl<'sc> ParseTree<'sc> {
+    /// Create a new, empty, [ParseTree] from a span which represents the source code that it will
+    /// cover.
     pub(crate) fn new(span: span::Span<'sc>) -> Self {
         ParseTree {
             root_nodes: Vec::new(),
             span,
         }
     }
-}
 
-impl<'sc> ParseTree<'sc> {
+    /// Push a new [AstNode] on to the end of a [ParseTree]'s root nodes.
     pub(crate) fn push(&mut self, new_node: AstNode<'sc>) {
         self.root_nodes.push(new_node);
     }
 }
 
+/// Given an input `str` and an optional [BuildConfig], parse the input into a [HllParseTree].
+///
+/// Here, the `'sc` lifetime is introduced to the compilation process. It stands for _source code_,
+/// and all references to `'sc` in the compiler refer to the lifetime of the original source input
+/// `str`.
+///
+/// # Example
+/// ```
+/// # use core_lang::parse;
+/// # fn main() {
+///     let input = "script; fn main() -> bool { true }";
+///     let result = parse(input, Default::default());
+/// # }
+/// ```
+///
+/// # Panics
+/// Panics if the generated parser from Pest panics.
 pub fn parse<'sc>(
     input: &'sc str,
     config: Option<&BuildConfig>,
@@ -129,6 +173,8 @@ pub fn parse<'sc>(
     ok(res, warnings, errors)
 }
 
+/// Represents the result of compiling Sway code via `compile_to_asm`.
+/// Contains the compiled assets or resulting errors, and any warnings generated.
 pub enum CompilationResult<'sc> {
     Success {
         asm: FinalizedAsm<'sc>,
@@ -143,6 +189,9 @@ pub enum CompilationResult<'sc> {
         errors: Vec<CompileError<'sc>>,
     },
 }
+
+/// Represents the result of compiling Sway code via `compile_to_bytecode`.
+/// Contains the compiled bytecode in byte form, or, resulting errors, and any warnings generated.
 pub enum BytecodeCompilationResult<'sc> {
     Success {
         bytes: Vec<u8>,
@@ -157,6 +206,8 @@ pub enum BytecodeCompilationResult<'sc> {
     },
 }
 
+/// If a given [Rule] exists in the input text, return
+/// that string trimmed. Otherwise, return `None`. This is typically used to find keywords.
 pub fn extract_keyword(line: &str, rule: Rule) -> Option<&str> {
     if let Ok(pair) = HllParser::parse(rule, line) {
         Some(pair.as_str().trim())
@@ -165,13 +216,15 @@ pub fn extract_keyword(line: &str, rule: Rule) -> Option<&str> {
     }
 }
 
+/// Takes a parse failure as input and returns either the index of the positional pest parse error, or the start position of the span of text that the error occurs.
 fn get_start(err: &pest::error::Error<Rule>) -> usize {
     match err.location {
         pest::error::InputLocation::Pos(num) => num,
         pest::error::InputLocation::Span((start, _)) => start,
     }
 }
 
+/// Takes a parse failure as input and returns either the index of the positional pest parse error, or the end position of the span of text that the error occurs.
 fn get_end(err: &pest::error::Error<Rule>) -> usize {
     match err.location {
         pest::error::InputLocation::Pos(num) => num,
@@ -263,6 +316,8 @@ pub(crate) fn compile_inner_dependency<'sc>(
     )
 }
 
+/// Given input Sway source code, compile to a [CompilationResult] which contains the asm in opcode
+/// form (not raw bytes/bytecode).
 pub fn compile_to_asm<'sc>(
     input: &'sc str,
     initial_namespace: &Namespace<'sc>,
@@ -338,6 +393,9 @@ pub fn compile_to_asm<'sc>(
         }
     }
 }
+
+/// Given input Sway source code, compile to a [BytecodeCompilationResult] which contains the asm in
+/// bytecode form.
 pub fn compile_to_bytecode<'n, 'sc>(
     input: &'sc str,
     initial_namespace: &Namespace<'sc>,
@@ -374,6 +432,8 @@ pub fn compile_to_bytecode<'n, 'sc>(
     }
 }
 
+/// Given a [TypedParseTree], which is type-checked Sway source, construct a graph to analyze
+/// control flow and determine if it is valid.
 fn perform_control_flow_analysis<'sc>(
     tree: &TypedParseTree<'sc>,
     tree_type: &TreeType<'sc>,
@@ -391,9 +451,8 @@ fn perform_control_flow_analysis<'sc>(
     (warnings, errors)
 }
 
-// strategy: parse top level things
-// and if we encounter a function body or block, recursively call this function and build
-// sub-nodes
+/// The basic recursive parser which handles the top-level parsing given the output of the
+/// pest-generated parser.
 fn parse_root_from_pairs<'sc>(
     input: impl Iterator<Item = Pair<'sc, Rule>>,
     config: Option<&BuildConfig>,

diff --git a/core_lang/src/parse_tree/mod.rs → core_lang/src/parse_tree.rs b/core_lang/src/parse_tree/mod.rs → core_lang/src/parse_tree.rs
@@ -1,3 +1,4 @@
+//! Contains all the code related to parsing Sway source code.
 mod call_path;
 mod code_block;
 pub mod declaration;

diff --git a/core_lang/src/semantic_analysis/mod.rs → core_lang/src/semantic_analysis.rs b/core_lang/src/semantic_analysis/mod.rs → core_lang/src/semantic_analysis.rs
@@ -1,3 +1,4 @@
+//! Type checking for Sway.
 pub mod ast_node;
 mod namespace;
 mod node_dependencies;

diff --git a/core_lang/src/types/mod.rs → core_lang/src/types.rs b/core_lang/src/types/mod.rs → core_lang/src/types.rs
@@ -1,2 +1,3 @@
+//! Contains post-type-engine resolved types.
 mod resolved_type;
 pub use resolved_type::ResolvedType;