diff --git a/asg/src/checks/mod.rs b/asg/src/checks/mod.rs
index 98f973c3e5..d143db3fa2 100644
--- a/asg/src/checks/mod.rs
+++ b/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 .
+//! Helper methods to determine the correct return value path in an asg.
+
mod return_path;
pub use return_path::*;
diff --git a/asg/src/const_value.rs b/asg/src/const_value.rs
index 7e82cf9377..8d70a5142b 100644
--- a/asg/src/const_value.rs
+++ b/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,
}
diff --git a/asg/src/error/mod.rs b/asg/src/error/mod.rs
index 502953da66..4419793449 100644
--- a/asg/src/error/mod.rs
+++ b/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 .
+//! 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;
diff --git a/asg/src/expression/circuit_access.rs b/asg/src/expression/circuit_access.rs
index d28219bb08..b4f1e3a536 100644
--- a/asg/src/expression/circuit_access.rs
+++ b/asg/src/expression/circuit_access.rs
@@ -148,7 +148,7 @@ impl FromAst 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(
diff --git a/asg/src/expression/mod.rs b/asg/src/expression/mod.rs
index 86d812d8d6..de3c6f6f32 100644
--- a/asg/src/expression/mod.rs
+++ b/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 .
+//! 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::*;
diff --git a/asg/src/import.rs b/asg/src/import.rs
index c65e29d884..8924530b0f 100644
--- a/asg/src/import.rs
+++ b/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 .
+//! Helper methods for resolving imported packages.
+
use crate::{AsgConvertError, Program, Span};
use indexmap::IndexMap;
diff --git a/asg/src/input.rs b/asg/src/input.rs
index 32aa4ae7ff..18023bd6fd 100644
--- a/asg/src/input.rs
+++ b/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,
@@ -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 {
@@ -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
)
}
}
diff --git a/asg/src/lib.rs b/asg/src/lib.rs
index db207af27c..6e26852f07 100644
--- a/asg/src/lib.rs
+++ b/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 .
+
+//! 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,
diff --git a/asg/src/node.rs b/asg/src/node.rs
index 3e56ce9a0c..e121a3c9f4 100644
--- a/asg/src/node.rs
+++ b/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>;
}
diff --git a/asg/src/program/mod.rs b/asg/src/program/mod.rs
index 061fb4c7d8..3c549a37aa 100644
--- a/asg/src/program/mod.rs
+++ b/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 .
+//! This module defines the program node for an asg.
+//!
+//!
+
mod circuit;
pub use circuit::*;
diff --git a/asg/src/reducer/mod.rs b/asg/src/reducer/mod.rs
index f471d9511d..95f82553eb 100644
--- a/asg/src/reducer/mod.rs
+++ b/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 .
+//! This module contains the reducer which iterates through ast nodes - converting them into
+//! asg nodes and saving relevant information.
+
mod monoid;
pub use monoid::*;
diff --git a/asg/src/scope.rs b/asg/src/scope.rs
index 2a8114f2bd..4092e804a6 100644
--- a/asg/src/scope.rs
+++ b/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 .
-// 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>;
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.
diff --git a/asg/src/statement/mod.rs b/asg/src/statement/mod.rs
index 910ca629b2..51477a4532 100644
--- a/asg/src/statement/mod.rs
+++ b/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 .
+//! 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::*;
diff --git a/asg/src/type_.rs b/asg/src/type_.rs
index 2ffabeefba..ac71b3b8c7 100644
--- a/asg/src/type_.rs
+++ b/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),
}
+/// TODO (@protryon): Please provide comments.
#[derive(Clone)]
pub enum WeakType {
Type(Type), // circuit not allowed
Circuit(Weak),
}
+/// TODO (@protryon): Please provide comments.
#[derive(Clone, PartialEq)]
pub enum PartialType {
Type(Type), // non-array or tuple
diff --git a/asg/src/variable.rs b/asg/src/variable.rs
index 59cc32b949..2314c853f1 100644
--- a/asg/src/variable.rs
+++ b/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,