Added more documentation & small fixes (FuelLabs#455)

* example docs

* type refactor

* Document lib.rs

* document modules

* fix typo

* removed merge conflict markers

* added parse functionality to  function use example

* Added more documentation, and small fixes

* accepted incoming changes

* small fix that got reverted

* Update core_lang/src/ident.rs

Co-authored-by: Alex Hansen <[email protected]>

* Update core_lang/src/parse_tree/expression/mod.rs

Co-authored-by: Alex Hansen <[email protected]>

* Update core_lang/src/span.rs

Co-authored-by: Alex Hansen <[email protected]>

* Update to docstring for `Ident`

Added note for distinction between "symbols" and "tokens".

* added more docs for review

* added UseStatement

* formatting

* Added hyperlinks and fixed local broken link

* Requested changes to docs

* Requested changes

Co-authored-by: Alex Hansen <[email protected]>
Co-authored-by: John Adler <[email protected]>

sway-core/src/ident.rs

@@ -6,6 +6,7 @@ use pest::iterators::Pair;
 use std::cmp::{Ord, Ordering};
 use std::hash::{Hash, Hasher};
 
+/// An [Ident] is an _identifier_ with a corresponding `span` from which it was derived.
 #[derive(Debug, Clone)]
 pub struct Ident<'sc> {
     pub primary_name: &'sc str,

sway-core/src/lib.rs

@@ -159,7 +159,7 @@ pub fn parse<'sc>(
     ok(parsed_root, warnings, errors)
 }
 
-/// Represents the result of compiling Sway code via `compile_to_asm`.
+/// 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 {
@@ -189,8 +189,8 @@ pub enum CompileAstResult<'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.
+/// 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>,

sway-core/src/parse_tree/expression/mod.rs

@@ -27,6 +27,7 @@ pub(crate) use method_name::MethodName;
 pub(crate) use scrutinee::{Scrutinee, StructScrutineeField};
 pub(crate) use unary_op::UnaryOp;
 
+/// Represents a parsed, but not yet type checked, [Expression](https://en.wikipedia.org/wiki/Expression_(computer_science)).
 #[derive(Debug, Clone)]
 pub enum Expression<'sc> {
     Literal {
@@ -86,7 +87,7 @@ pub enum Expression<'sc> {
         arguments: Vec<Expression<'sc>>,
         span: Span<'sc>,
     },
-    /// A subfield expression is anything of the form:
+    /// A _subfield expression_ is anything of the form:
     /// ```ignore
     /// <ident>.<ident>
     /// ```
@@ -96,7 +97,7 @@ pub enum Expression<'sc> {
         span: Span<'sc>,
         field_to_access: Ident<'sc>,
     },
-    /// A [DelineatedPath] is anything of the form:
+    /// A _delineated path_ is anything of the form:
     /// ```ignore
     /// <ident>::<ident>
     /// ```

sway-core/src/parse_tree/use_statement.rs

@@ -11,6 +11,7 @@ pub enum ImportType<'sc> {
     Item(Ident<'sc>),
 }
 
+/// A [UseStatement] is a statement that imports something from a module into the local namespace.
 #[derive(Debug, Clone)]
 pub struct UseStatement<'sc> {
     pub(crate) call_path: Vec<Ident<'sc>>,

sway-core/src/parse_tree/while_loop.rs

@@ -7,6 +7,7 @@ use crate::{
 };
 use pest::iterators::Pair;
 
+/// A parsed while loop. Contains the `condition`, which is defined from an [Expression], and the `body` from a [CodeBlock].
 #[derive(Debug, Clone)]
 pub struct WhileLoop<'sc> {
     pub(crate) condition: Expression<'sc>,

sway-core/src/parser.rs

@@ -1,3 +1,5 @@
+/// Represents the high level language parser generated by [pest].
+/// [Rule] is also generated here by [pest].
 #[derive(Parser)]
 #[grammar = "hll.pest"]
 pub struct HllParser;

sway-core/src/semantic_analysis/ast_node/declaration.rs

@@ -201,7 +201,7 @@ impl<'sc> TypedDeclaration<'sc> {
     }
 }
 
-/// A `TypedAbiDeclaration` contains the type-checked version of the parse tree's [AbiDeclaration].
+/// A `TypedAbiDeclaration` contains the type-checked version of the parse tree's `AbiDeclaration`.
 #[derive(Clone, Debug)]
 pub struct TypedAbiDeclaration<'sc> {
     /// The name of the abi trait (also known as a "contract trait")

sway-core/src/semantic_analysis/namespace.rs

@@ -16,21 +16,23 @@ use std::collections::{BTreeMap, HashMap, VecDeque};
 type ModuleName = String;
 type TraitName<'a> = CallPath<'a>;
 
+/// A namespace represents all items that exist either via declaration or importing.
 #[derive(Clone, Debug, Default)]
 pub struct Namespace<'sc> {
     // This is a BTreeMap because we rely on its ordering being consistent. See
     // [Namespace::get_all_declared_symbols] -- we need that iterator to have a deterministic
     // order.
     symbols: BTreeMap<Ident<'sc>, TypedDeclaration<'sc>>,
     implemented_traits: HashMap<(TraitName<'sc>, TypeInfo), Vec<TypedFunctionDeclaration<'sc>>>,
-    /// any imported namespaces associated with an ident which is a  library name
+    // Any other modules within this scope, where a module is a namespace associated with an identifier.
     // This is a BTreeMap because we rely on its ordering being consistent. See
     // [Namespace::get_all_imported_modules] -- we need that iterator to have a deterministic
     // order.
     modules: BTreeMap<ModuleName, Namespace<'sc>>,
-    /// The crate namespace, to be used in absolute importing. This is `None` if the current
-    /// namespace _is_ the root namespace.
+    // The crate namespace, to be used in absolute importing. This is `None` if the current
+    // namespace _is_ the root namespace.
     use_synonyms: HashMap<Ident<'sc>, Vec<Ident<'sc>>>,
+    // Represents an alternative name for a symbol.
     use_aliases: HashMap<String, Ident<'sc>>,
 }
 

sway-core/src/semantic_analysis/syntax_tree.rs

@@ -11,6 +11,7 @@ use crate::{AstNode, ParseTree};
 
 use std::collections::{HashMap, HashSet};
 
+/// Represents the different variants of the AST.
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub enum TreeType<'sc> {
     Predicate,

sway-core/src/span.rs

@@ -1,8 +1,11 @@
 use std::{path::PathBuf, sync::Arc};
 
+/// Represents a span of the source code in a specific file.
 #[derive(Debug, Clone, Eq, PartialEq, Hash)]
 pub struct Span<'sc> {
+    ///  A [pest::Span] returned directly from the generated parser.
     pub span: pest::Span<'sc>,
+    // A reference counted pointer to the file from which this span originated.
     pub(crate) path: Option<Arc<PathBuf>>,
 }
 

sway-types/src/lib.rs

@@ -13,7 +13,7 @@ pub struct Position {
     pub col: usize,
 }
 
-/// Based on https://llvm.org/docs/CoverageMappingFormat.html#source-code-range
+/// Based on `<https://llvm.org/docs/CoverageMappingFormat.html#source-code-range>`
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
 pub struct Range {
     /// Beginning of the code range
@@ -332,7 +332,7 @@ impl Context {
 }
 
 /// Fuel/Sway ABI representation in JSON, originally
-/// specified here: https://github.com/FuelLabs/fuel-specs/blob/master/specs/protocol/abi.md
+/// specified here: `<https://github.com/FuelLabs/fuel-specs/blob/master/specs/protocol/abi.md>`
 /// This type is used by the compiler and the tooling around it convert
 /// an ABI representation into native Rust structs and vice-versa.
 pub type JsonABI = Vec<Function>;