comment on asg modules

asg/src/checks/mod.rs

@@ -14,5 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with the Leo library. If not, see <https://www.gnu.org/licenses/>.
 
+//! Helper methods to determine the correct return value path in an asg.
+
 mod return_path;
 pub use return_path::*;

asg/src/const_value.rs

@@ -19,6 +19,7 @@ use crate::{AsgConvertError, IntegerType, Span, Type};
 use num_bigint::BigInt;
 use std::{convert::TryInto, fmt};
 
+/// Constant integer values in a program.
 #[derive(Clone, Debug, PartialEq)]
 pub enum ConstInt {
     I8(i8),
@@ -33,11 +34,19 @@ pub enum ConstInt {
     U128(u128),
 }
 
+/// Specifies how to calculate a group coordinate in a program.
 #[derive(Clone, Debug, PartialEq)]
 pub enum GroupCoordinate {
+    /// Explicit field element number string.
     Number(String),
+
+    /// Attempt to recover with a sign high bit.
     SignHigh,
+
+    /// Attempt to recover with a sign low bit.
     SignLow,
+
+    /// Try recovering with a sign low - upon failure try sign high.
     Inferred,
 }
 

asg/src/error/mod.rs

@@ -14,6 +14,8 @@
 // You should have received a copy of the GNU General Public License
 // along with the Leo library. If not, see <https://www.gnu.org/licenses/>.
 
+//! Errors encountered when attempting to convert to an asg from an ast.
+
 use crate::Span;
 use leo_ast::Error as FormattedError;
 use leo_grammar::ParserError;

asg/src/expression/circuit_access.rs

@@ -148,7 +148,7 @@ impl FromAst<leo_ast::CircuitMemberAccessExpression> for CircuitAccessExpression
 
         if found_member {
             // skip
-        } else if circuit.is_input_psuedo_circuit() {
+        } else if circuit.is_input_pseudo_circuit() {
             // add new member to implicit input
             if let Some(expected_type) = expected_type.map(PartialType::full).flatten() {
                 circuit.members.borrow_mut().insert(

asg/src/expression/mod.rs

@@ -14,6 +14,12 @@
 // You should have received a copy of the GNU General Public License
 // along with the Leo library. If not, see <https://www.gnu.org/licenses/>.
 
+//! This module defines an expression node in an asg.
+//!
+//! Notable differences after conversion from an ast expression include:
+//! 1. Storing variable references instead of variable identifiers - better history tracking and mutability
+//! 2. Resolving constant values - optimizes execution of program circuit.
+
 mod array_access;
 pub use array_access::*;
 

asg/src/import.rs

@@ -14,6 +14,8 @@
 // You should have received a copy of the GNU General Public License
 // along with the Leo library. If not, see <https://www.gnu.org/licenses/>.
 
+//! Helper methods for resolving imported packages.
+
 use crate::{AsgConvertError, Program, Span};
 
 use indexmap::IndexMap;

asg/src/input.rs

@@ -22,6 +22,7 @@ use std::{
     sync::{Arc, Weak},
 };
 
+/// Stores program input values as asg nodes.
 #[derive(Clone)]
 pub struct Input {
     pub registers: Arc<CircuitBody>,
@@ -32,11 +33,11 @@ pub struct Input {
     pub container: Variable,
 }
 
-pub const CONTAINER_PSUEDO_CIRCUIT: &str = "$InputContainer";
-pub const REGISTERS_PSUEDO_CIRCUIT: &str = "$InputRegister";
-pub const RECORD_PSUEDO_CIRCUIT: &str = "$InputRecord";
-pub const STATE_PSUEDO_CIRCUIT: &str = "$InputState";
-pub const STATE_LEAF_PSUEDO_CIRCUIT: &str = "$InputStateLeaf";
+pub const CONTAINER_PSEUDO_CIRCUIT: &str = "$InputContainer";
+pub const REGISTERS_PSEUDO_CIRCUIT: &str = "$InputRegister";
+pub const RECORD_PSEUDO_CIRCUIT: &str = "$InputRecord";
+pub const STATE_PSEUDO_CIRCUIT: &str = "$InputState";
+pub const STATE_LEAF_PSEUDO_CIRCUIT: &str = "$InputStateLeaf";
 
 impl Input {
     fn make_header(name: &str) -> Arc<Circuit> {
@@ -61,10 +62,10 @@ impl Input {
     }
 
     pub fn new(scope: &Scope) -> Self {
-        let registers = Self::make_header(REGISTERS_PSUEDO_CIRCUIT);
-        let record = Self::make_header(RECORD_PSUEDO_CIRCUIT);
-        let state = Self::make_header(STATE_PSUEDO_CIRCUIT);
-        let state_leaf = Self::make_header(STATE_LEAF_PSUEDO_CIRCUIT);
+        let registers = Self::make_header(REGISTERS_PSEUDO_CIRCUIT);
+        let record = Self::make_header(RECORD_PSEUDO_CIRCUIT);
+        let state = Self::make_header(STATE_PSEUDO_CIRCUIT);
+        let state_leaf = Self::make_header(STATE_LEAF_PSEUDO_CIRCUIT);
 
         let mut container_members = IndexMap::new();
         container_members.insert(
@@ -86,7 +87,7 @@ impl Input {
 
         let container_circuit = Arc::new(Circuit {
             id: uuid::Uuid::new_v4(),
-            name: RefCell::new(Identifier::new(CONTAINER_PSUEDO_CIRCUIT.to_string())),
+            name: RefCell::new(Identifier::new(CONTAINER_PSEUDO_CIRCUIT.to_string())),
             body: RefCell::new(Weak::new()),
             members: RefCell::new(container_members),
             core_mapping: RefCell::new(None),
@@ -137,10 +138,10 @@ impl Input {
 }
 
 impl Circuit {
-    pub fn is_input_psuedo_circuit(&self) -> bool {
+    pub fn is_input_pseudo_circuit(&self) -> bool {
         matches!(
             &*self.name.borrow().name,
-            REGISTERS_PSUEDO_CIRCUIT | RECORD_PSUEDO_CIRCUIT | STATE_PSUEDO_CIRCUIT | STATE_LEAF_PSUEDO_CIRCUIT
+            REGISTERS_PSEUDO_CIRCUIT | RECORD_PSEUDO_CIRCUIT | STATE_PSEUDO_CIRCUIT | STATE_LEAF_PSEUDO_CIRCUIT
         )
     }
 }

asg/src/lib.rs

@@ -13,6 +13,15 @@
 
 // You should have received a copy of the GNU General Public License
 // along with the Leo library. If not, see <https://www.gnu.org/licenses/>.
+
+//! The abstract semantic graph (asg) for a Leo program.
+//!
+//! This module contains the [`Asg`] type, an abstract data type that represents a Leo program
+//! as a series of graph nodes. The [`Asg`] type is at a greater level of abstraction than an [`Ast`].
+//!
+//! A new [`Asg`] type can be created from an [`Ast`].
+//! Converting to an [`Asg`] provides greater type safety by canonicalizing and checking program types.
+
 #![allow(clippy::from_over_into)]
 #[macro_use]
 extern crate thiserror;
@@ -63,13 +72,12 @@ pub use leo_ast::{Identifier, Span};
 
 use std::path::Path;
 
-/// The abstract syntax graph (asg) for a Leo program.
+/// The abstract semantic graph (asg) for a Leo program.
 ///
 /// The [`Asg`] type represents a Leo program as a series of recursive data types.
-/// These data types form a graph that begins from a [`Program`] type root.
+/// These data types form a graph that begins from a [`Program`] type node.
 ///
 /// A new [`Asg`] can be created from an [`Ast`] generated in the `ast` module.
-// TODO (protryon): please uncomment and mirror the implementation from Ast. This should be the only entrypoint called by the compiler module.
 // #[derive(Debug, Eq, PartialEq)]
 // pub struct Asg {
 //     asg: InnerProgram,

asg/src/node.rs

@@ -16,6 +16,7 @@
 
 use crate::{AsgConvertError, PartialType, Scope, Span};
 
+/// A node in the abstract semantic graph.
 pub trait Node {
     fn span(&self) -> Option<&Span>;
 }

asg/src/program/mod.rs

@@ -14,6 +14,10 @@
 // You should have received a copy of the GNU General Public License
 // along with the Leo library. If not, see <https://www.gnu.org/licenses/>.
 
+//! This module defines the program node for an asg.
+//!
+//!
+
 mod circuit;
 pub use circuit::*;
 

asg/src/reducer/mod.rs

@@ -14,6 +14,9 @@
 // You should have received a copy of the GNU General Public License
 // along with the Leo library. If not, see <https://www.gnu.org/licenses/>.
 
+//! This module contains the reducer which iterates through ast nodes - converting them into
+//! asg nodes and saving relevant information.
+
 mod monoid;
 pub use monoid::*;
 

asg/src/scope.rs

@@ -14,14 +14,12 @@
 // You should have received a copy of the GNU General Public License
 // along with the Leo library. If not, see <https://www.gnu.org/licenses/>.
 
-// TODO (protryon): Please order dependencies in two groups alphabetically 1. Our dependencies 2. Everyone else's
 use crate::{AsgConvertError, Circuit, Function, Input, Type, Variable};
 
 use indexmap::IndexMap;
 use std::{cell::RefCell, sync::Arc};
 use uuid::Uuid;
 
-// TODO (protryon): Struct defs should have a description of the data type and field.
 /// An abstract data type that track the current bindings for variables, functions, and circuits.
 pub struct InnerScope {
     /// The unique id of the scope.
@@ -52,9 +50,8 @@ pub struct InnerScope {
 pub type Scope = Arc<RefCell<InnerScope>>;
 
 impl InnerScope {
-    // TODO (protryon): Function definitions should have one extra line above and below the description.
     ///
-    /// Returns a reference to the variable corresponding to the name. TODO (protryon): The description should clearly state the function's return and given arguments.
+    /// Returns a reference to the variable corresponding to the name.
     ///
     /// If the current scope did not have this name present, then the parent scope is checked.
     /// If there is no parent scope, then `None` is returned.

asg/src/statement/mod.rs

@@ -14,6 +14,10 @@
 // You should have received a copy of the GNU General Public License
 // along with the Leo library. If not, see <https://www.gnu.org/licenses/>.
 
+//! This module defines a statement node in an asg.
+//!
+//! Ast statement nodes can be directly converted into asg nodes with no major differences.
+
 mod assign;
 pub use assign::*;
 

asg/src/type_.rs

@@ -22,6 +22,7 @@ use std::{
     sync::{Arc, Weak},
 };
 
+/// A type in an asg.
 #[derive(Clone, PartialEq)]
 pub enum Type {
     // Data types
@@ -37,12 +38,14 @@ pub enum Type {
     Circuit(Arc<Circuit>),
 }
 
+/// TODO (@protryon): Please provide comments.
 #[derive(Clone)]
 pub enum WeakType {
     Type(Type), // circuit not allowed
     Circuit(Weak<Circuit>),
 }
 
+/// TODO (@protryon): Please provide comments.
 #[derive(Clone, PartialEq)]
 pub enum PartialType {
     Type(Type), // non-array or tuple

asg/src/variable.rs

@@ -23,6 +23,7 @@ use std::{
 };
 use uuid::Uuid;
 
+/// Specifies how a program variable was declared.
 pub enum VariableDeclaration {
     Definition,
     IterationDefinition,
@@ -30,6 +31,7 @@ pub enum VariableDeclaration {
     Input,
 }
 
+/// Stores information on a program variable.
 pub struct InnerVariable {
     pub id: Uuid,
     pub name: Identifier,