Merge pull request #315 from 0xPolygonMiden/docs/copy-edit-1

docs: first pass applying Polygon-wide documentation standards

.gitignore

@@ -3,3 +3,15 @@ bin/midenc
 bin/litcheck
 .crates.toml
 .crates2.json
+
+# Docs platform ignores
+.vscode
+.code
+.idea
+site/
+venv/
+env/
+*.out
+node_modules/
+*DS_Store
+*.iml

Makefile.toml

@@ -256,13 +256,13 @@ category = "Test"
 description = "Set up the litcheck utility"
 install_crate = { crate_name = "litcheck", test_arg = "--help" }
 
-[tasks.book]
+[tasks.docs]
 category = "Build"
 description = "Builds the compiler documentation"
 command = "docs/mkdocs"
 args = ["build", "-d", "target/docs/site"]
 
-[tasks.serve-book]
+[tasks.serve-docs]
 category = "Build"
 description = "Opens the compiler documentation"
 command = "docs/mkdocs"

docs/README.txt

@@ -4,6 +4,35 @@ This directory contains the sources for the [Miden Compiler Documentation](https
 
 All doc files are written in Markdown, and are converted into an online book using [mkdocs](https://squidfunk.github.io/mkdocs-material/).
 
-# License
+## Building the docs
+
+You can build and view the documentation using two different methods, depending on whether or not
+you have `cargo` installed.
+
+**NOTE:** Both methods described below are expected to be run from the root of the compiler project.
+
+### Using `cargo`
+
+To build the docs, use `cargo make docs`. This will place the build output in the `target/docs/site`
+directory.
+
+If you wish to build the docs _and_ run a server to view them, which will reload when changes are
+made, use `cargo make serve-docs`. The hostname and port will be displayed in the terminal, but by
+default the docs should be available at `http://127.0.0.1:8000`.
+
+### Using `mkdocs` script
+
+If you don't have `cargo` installed, you can use this method instead. Again, the commands below are
+written with the current working directory being the root of the compiler project, _not_ this
+directory.
+
+To build the docs, use `docs/mkdocs build -d target/docs/site`. This matches the behavior of the
+`cargo make docs` command.
+
+To view the docs in your browser, with reload on change enabled, use `docs/mkdocs serve`. The
+hostname and port where the docs can be viewed will be printed to the terminal, but by default this
+is `http://127.0.0.1:8000`.
+
+## License
 
 MIT

docs/appendix/calling_conventions.md → docs/appendix/calling-conventions.md

@@ -1,4 +1,4 @@
-# Calling Conventions
+# Calling conventions
 
 This document describes the various calling conventions recognized/handled by the compiler,
 including a specification for the interaction with the IR type system.
@@ -25,17 +25,16 @@ There are four calling conventions represented in the compiler:
   convention is allowed to have types in its signature that are/contain pointers, with certain caveats around
   those pointers.
 
-
 All four conventions above are based on the System V C ABI, tailored to the Miden VM. The only exception is
 `Fast`, which may modify the ABI arbitrarily as it sees fit, and makes no guarantees about what modifications,
 if any, it will make.
 
-# Data Representation
+## Data representation
 
 The following is a description of how the IR type system is represented in the `C` calling convention. Later,
 a description of how the other conventions extend/restrict/modify this representation will be provided.
 
-## Scalars
+### Scalars
 
 General type | C Type | IR Type | `sizeof` | Alignment (bytes) | Miden Type
 -|-|-|-|-|-
@@ -101,14 +100,14 @@ two's complement rules.
 The Miden VM only has native support for field elements, words, and `u32`; all other types are implemented in software
 using intrinsics.
 
-## Aggregates and Unions
+### Aggregates and unions
 
 Structures and unions assume the alignment of their most strictly aligned component. Each member is assigned to the
 lowest available offset with the appropriate alignment. The size of any object is always a multiple of the object's alignment.
 An array uses the same alignment as its elements. Structure and union objects can require padding to meet size and alignment
 constraints. The contents of any padding is undefined.
 
-## Memory Model
+### Memory model
 
 Interacting with memory in Miden is quite similar to WebAssembly in some ways:
 
@@ -176,12 +175,12 @@ word-aligned or element-aligned, so an unaligned load or store would require eit
 bytes starting at some arbitrary address. In practice, most loads/stores are likely to be element-aligned, so most overhead from
 emulation will come from values which cross an element or word boundary.
 
-# Function Calls
+## Function calls
 
 This section describes the conventions followed when executing a function call via `exec`, including how arguments are passed on the
 operand stack, stack frames, etc. Later, we'll cover the differences when executing calls via `call` or `syscall`.
 
-## Locals and the stack frame
+### Locals and the stack frame
 
 Miden does not have registers in the style of hardware architectures. Instead it has an operand stack, on which an arbitrary number of
 operands may be stored, and local variables. In both cases - an operand on the operand stack, or a single local variable - the value
@@ -201,7 +200,7 @@ Because there are no registers, the notion of callee-saved or caller-saved regis
 in its place, a somewhat equivalent set of rules defines the contract between caller and callee in terms of the state of the operand stack,
 those are described below in the section covering the operand stack.
 
-### The shadow stack
+#### The shadow stack
 
 Miden is a [Harvard](https://en.wikipedia.org/wiki/Harvard_architecture) architecture; as such, code and data are not in the same memory
 space. More precisely, in Miden, code is only addressable via the hash of the MAST root of that code, which must correspond to code that
@@ -222,7 +221,7 @@ constraints of the callee's calling convention).
 Languages with more elaborate requirements with regard to the stack will need to implement their own shadow stack, and emit code in function
 prologues/epilogues to manage it.
 
-### The operand stack
+#### The operand stack
 
 The Miden virtual machine is a stack machine, not a register machine. Rather than having a fixed set of registers that are used to
 store and manipulate scalar values, the Miden VM has the operand stack, which can hold an arbitrary number of operands (where each
@@ -246,7 +245,7 @@ then one of the following must happen:
   which refers to the remaining arguments on the advice provider stack. The callee must arrange to fetch the spilled arguments from the advice
   provider using that hash.
 
-### Function signatures
+#### Function signatures
 
 Miden Abstract Syntax Trees (MASTs) do not have any notion of functions, and as such are not aware of parameters, return values, etc. For
 this document, that's not a useful level of abstraction to examine. Even a step higher, Miden Assembly (MASM) has functions (procedures

docs/appendix/canonabi-adhocabi-mismatch.md

@@ -1,4 +1,4 @@
-# Canonical ABI vs Miden ABI Incompatibility
+# Canonical ABI vs Miden ABI incompatibility
 
 This document describes an issue that arises when trying to map the ad-hoc calling convention/ABI
 used by various Miden Assembly procedures, such as those comprising the transaction kernel, and
@@ -140,7 +140,7 @@ library is a part of the Miden compiler. It is not anticipated that we will have
 these; however in the near term we are going to manually map procedures to their adapter strategies,
 as we have not yet automated the pattern recognition step.
 
-### Return-via-pointer Adapter
+### Return-via-pointer adapter
 
 The return value is expected to be returned by storing its flattened representation in a pointer
 passed as an argument.
@@ -174,7 +174,7 @@ func wasm_core_add_asset(v0: f64, v1: f64, v2: f64, v3: f64, ptr: i32) {
 }
 ```
 
-### No-op Adapter
+### No-op adapter
 
 No adapter is needed. The Wasm core function type is the same as the tx kernel ad-hoc signature.
 
@@ -183,7 +183,7 @@ This Miden ABI pattern is selected if no other Miden ABI pattern is applicable a
 For example, the `get_id` function falls under this Miden ABI pattern and its calls will be translated to the tx kernel function calls without any modifications.
 
 
-## Transaction kernel functions that require manual adapter functions:
+## Transaction kernel functions that require manual adapter functions
 
 ### `get_assets`
 

docs/appendix/known-limitations.md

@@ -1,4 +1,4 @@
-# Known Limitations
+# Known limitations
 
 !!! tip
 
@@ -13,9 +13,9 @@ important to be aware of this when using the compiler.
 The features discussed below are broken up into sections, to make them easier to navigate and
 reference.
 
-## Rust Language Support
+## Rust language support
 
-### Floating Point Types
+### Floating point types
 
 - Status: **Unsupported**
 - Tracking Issue: N/A
@@ -34,8 +34,7 @@ first place.
 At this point in time, we have no plans to support floats, but this may change if we are able to
 find a better/more natural representation for `Felt` in WebAssembly.
 
-
-### Function Call Indirection
+### Function call indirection
 
 - Status: **Unimplemented**
 - Tracking Issue: [#32](https://github.com/0xPolygonMiden/compiler/issues/32)
@@ -55,7 +54,7 @@ will raise an error when it encounters any use of `call_indirect`.
     the amount of inlining that can occur. Even then, it may not be possible to remove some forms of
     indirection, in which case you will need to find another workaround.
 
-#### Iterator Lowered to Loop
+#### Iterator lowered to loop
 
 ```rust
 pub fn is_zeroed(bytes: &[u8; 32]) -> bool {
@@ -64,7 +63,7 @@ pub fn is_zeroed(bytes: &[u8; 32]) -> bool {
 }
 ```
 
-#### Monomorphization + Inlining
+#### Monomorphization + inlining
 
 ```rust
 pub fn call<F, T>(fun: F) -> T
@@ -84,7 +83,7 @@ fn main() {
 }
 ```
 
-#### Inlined Trait Impl
+#### Inlined trait impl
 
 ```rust
 pub trait Foo {
@@ -124,7 +123,7 @@ will be expanding the SDK rapidly over the next few weeks and months, but for th
 you encounter a missing API that you need, let us know, so we can ensure it is prioritized above
 APIs which are lesser used.
 
-### Rust/Miden FFI (Foreign Function Interface) and Interop
+### Rust/Miden FFI (foreign function interface) and interop
 
 - Status: **Internal Use Only**
 - Tracking Issue: [#304](https://github.com/0xPolygonMiden/compiler/issues/304)
@@ -148,9 +147,9 @@ procedures at a minimum, and in some cases we may require details of the calling
 This metadata does not currently exist, but is on the roadmap for inclusion into Miden Assembly
 and Miden packaging. Once present, we can open up the FFI for general use.
 
-## Core Miden Functionality
+## Core Miden functionality
 
-### Dynamic Procedure Invocation
+### Dynamic procedure invocation
 
 - Status: **Unimplemented**
 - Tracking Issue: [#32](https://github.com/0xPolygonMiden/compiler/issues/32)
@@ -175,7 +174,7 @@ the body of which drop the callee hash, fix up the operand stack as necessary, a
 simple `exec` or `call` to invoke the "real" callee. We will emit a single stub for every function
 which has its "address" taken, and use the hash of the stub in place of the actual callee hash.
 
-### Cross-Context Procedure Invocation
+### Cross-context procedure invocation
 
 - Status: **Unimplemented**
 - Tracking Issue: [#303](https://github.com/0xPolygonMiden/compiler/issues/303)
@@ -213,7 +212,7 @@ subfeatures being implemented first.
 
 ## Packaging
 
-### Package Format
+### Package format
 
 - Status: **Experimental**
 - Tracking Issue: [#121](https://github.com/0xPolygonMiden/compiler/issues/121)

docs/design/frontends.md

@@ -1,4 +1,4 @@
-# Supported Frontends
+# Supported front ends
 
 ## WebAssembly (Wasm)
 

docs/design/overview.md

@@ -1,4 +1,4 @@
-# Compiler Architecture
+# Compiler architecture
 
 This is an index of various design documents for the compiler and its components. Some of these
 are planned topics, and some have documentation that hasn't been polished up yet. We'll slowly

docs/guides/develop_miden_in_rust.md

@@ -1,10 +1,10 @@
-# Developing Miden Programs In Rust
+# Developing Miden programs in Rust
 
 This chapter will walk through how to develop Miden programs in Rust using the standard library
 provided by the `miden-stdlib-sys` crate (see the
-[README](https://github.com/0xPolygonMiden/compiler/sdk/stdlib-sys/README.md)).
+[README](https://github.com/0xPolygonMiden/compiler/blob/main/sdk/stdlib-sys/README.md).
 
-## Getting Started
+## Getting started
 
 Import the standard library from the `miden-stdlib-sys` crate:
 

docs/guides/develop_miden_rollup_accounts_and_note_scripts_in_rust.md

@@ -1,3 +1,3 @@
-# Developing Miden Rollup Accounts And Note Scripts In Rust
+# Developing Miden rollup accounts and note scripts in Rust
 
-This chapter will walk through how to develop Miden rollup accounts and note scripts in Rust using the Miden SDK crate.
+This chapter walks you through how to develop Miden rollup accounts and note scripts in Rust using the Miden SDK crate.

docs/guides/rust_to_wasm.md

@@ -168,7 +168,7 @@ Which dumps the following output (may differ slightly on your machine, depending
 
 Success!
 
-## Next Steps
+## Next steps
 
 In [Compiling WebAssembly to Miden Assembly](wasm_to_masm.md), we walk through how to take the
 WebAssembly module we just compiled, and lower it to Miden Assembly using `midenc`!

docs/guides/wasm_to_masm.md

@@ -122,7 +122,7 @@ We can test our compiled program like so:
 
 Success! We got the expected result of `55`.
 
-## Next Steps
+## Next steps
 
 This guide is not comprehensive, as we have not yet examined in detail the differences between
 compiling libraries vs programs, linking together multiple libraries, packages, or discussed some of

docs/index.md

@@ -1,6 +1,6 @@
-# Getting Started
+# Getting started
 
-Welcome to the documentation for the Miden compiler toolchain!
+Welcome to the documentation for the Miden compiler toolchain.
 
 !!! warning
 
@@ -78,7 +78,7 @@ We do not currently perform any optimizations on the IR, since we are primarily
 output of compiler backends which have already applied optimizations, at this time. This may change
 in the future, but for now it is expected that you implement your own optimization passes as needed.
 
-## Known Bugs and Limitations
+## Known bugs and limitations
 
 For the latest information on known bugs, see the [issue tracker](https://github.com/0xpolygonmiden/compiler/issues).
 

docs/usage/cargo-miden.md

@@ -1,4 +1,4 @@
-# Getting Started with Cargo
+# Getting started with Cargo
 
 As part of the Miden compiler toolchain, we provide a Cargo extension, `cargo-miden`, which provides
 a template to spin up a new Miden project in Rust, and takes care of orchestrating `rustc` and