docs: more architecture guide cleanups

Author: erikgrinaker

docs/architecture/server.md

@@ -12,50 +12,51 @@ For network protocol, the server uses the Bincode encoding that we've discussed
 section, sent over a TCP connection. There's no need for any further framing, since Bincode knows
 how many bytes to expect for each message depending on the type it's decoding into.
 
-The server does not use async Rust and e.g. [Tokio](https://tokio.rs), instead opting for regular OS
-threads. Async Rust can significantly complicate the code, which would obscure the main concepts,
-and any efficiency gains would be entirely irrelevant for toyDB.
+The server does not use [async Rust](https://rust-lang.github.io/async-book/) and e.g.
+[Tokio](https://tokio.rs), instead opting for regular OS threads. Async Rust can significantly
+complicate the code, which would obscure the main concepts, and any efficiency gains would be
+entirely irrelevant for toyDB.
 
 Internally in the server, messages are passed around between threads using
 [Crossbeam channels](https://docs.rs/crossbeam/latest/crossbeam/channel/index.html).
 
-The main server loop `Server::serve` listens for inbound TCP connections on port 9705 for Raft peers
-and 9605 for SQL clients, and spawns threads to process them. We'll look at Raft and SQL services
-separately.
+The main server loop `Server::serve()` listens for inbound TCP connections on port 9705 for Raft
+peers and 9605 for SQL clients, and spawns threads to process them. We'll look at Raft and SQL
+services separately.
 
 https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/server.rs#L66-L110
 
 ## Raft Routing
 
-The heart of the server is the Raft processing thread `Server::raft_route`. This is responsible
-for periodically ticking the Raft node via `raft::Node::tick`, stepping inbound messages from
-Raft peers into the node via `raft::Node::step`, and sending outbound messages to peers.
+The heart of the server is the Raft processing thread `Server::raft_route()`. This is responsible
+for periodically ticking the Raft node via `raft::Node::tick()`, stepping inbound messages from
+Raft peers into the node via `raft::Node::step()`, and sending outbound messages to peers.
 
 It also takes inbound Raft client requests from the `sql::engine::Raft` SQL engine, steps them
-into the Raft node via `raft::Node::step`, and passes responses back to the appropriate client
+into the Raft node via `raft::Node::step()`, and passes responses back to the appropriate client
 as the node emits them.
 
 https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/server.rs#L169-L249
 
-When the node starts up, it spawns a `Server::raft_send_peer` thread for each Raft peer to send
+When the node starts up, it spawns a `Server::raft_send_peer()` thread for each Raft peer to send
 outbound messages to them.
 
 https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/server.rs#L84-L91
 
 These threads continually attempt to connect to the peer via TCP, and then read any outbound
-`raft::Envelope(raft::Message)` messages from `Server::raft_route` via a channel and writes the
+`raft::Envelope(raft::Message)` messages from `Server::raft_route()` via a channel and writes the
 messages into the TCP connection using Bincode:
 
 https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/server.rs#L146-L167
 
 The server also continually listens for inbound Raft TCP connections from peers in
-`Server::raft_accept`:
+`Server::raft_accept()`:
 
 https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/server.rs#L112-L134
 
-When an inbound connection is accepted, a `Server::raft_receive_peer` thread is spawned that reads
+When an inbound connection is accepted, a `Server::raft_receive_peer()` thread is spawned that reads
 Bincode-encoded `raft::Envelope(raft::Message)` messages from the TCP connection and sends them to
-`Server::raft_route` via a channel.
+`Server::raft_route()` via a channel.
 
 https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/server.rs#L136-L144
 
@@ -72,13 +73,14 @@ The primary request type is `Request::Execute` which executes a SQL statement ag
 https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/server.rs#L312-L337
 
 The server sets up a `sql::engine::Raft` SQL engine, with a Crossbeam channel that's used to send
-`raft::Request` Raft client requests to `Server::raft_route` and onwards to the local `raft::Node`.
-It then spawns a `Server::sql_accept` thread to listen for inbound SQL client connections:
+`raft::Request` Raft client requests to `Server::raft_route()` and onwards to the local
+`raft::Node`.  It then spawns a `Server::sql_accept()` thread to listen for inbound SQL client
+connections:
 
 https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/server.rs#L104-L106
 
 When a SQL client connection is accepted, a new client session `sql::execution::Session` is set up
-for the client, and we spawn a `Server::sql_session` thread to serve the connection:
+for the client, and we spawn a `Server::sql_session()` thread to serve the connection:
 
 https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/server.rs#L251-L272
 

docs/architecture/sql-data.md

@@ -1,38 +1,45 @@
 # SQL Data Model
 
-The SQL data model is toyDB's representation of user data. It is made up of data types and schemas.
+The SQL data model represents user data in tables and rows. It is made up of data types and schemas,
+in the [`sql::types`](https://github.com/erikgrinaker/toydb/tree/686d3971a253bfc9facc2ba1b0e716cff5c109fb/src/sql/types)
+module.
 
 ## Data Types
 
-toyDB supports four basic scalar data types as `sql::types::DataType`: booleans, floats, integers,
+toyDB supports four basic scalar data types as `sql::types::DataType`: booleans, integers, floats,
 and strings.
 
 https://github.com/erikgrinaker/toydb/blob/b2fe7b76ee634ca6ad31616becabfddb1c03d34b/src/sql/types/value.rs#L15-L27
 
-Concrete values are represented as `sql::types::Value`, using corresponding Rust types. toyDB also
-supports SQL `NULL` values, i.e. unknown values, following the rules of
+Specific values are represented as `sql::types::Value`, using the corresponding Rust types. toyDB
+also supports SQL `NULL` values, i.e. unknown values, following the rules of
 [three-valued logic](https://en.wikipedia.org/wiki/Three-valued_logic).
 
 https://github.com/erikgrinaker/toydb/blob/b2fe7b76ee634ca6ad31616becabfddb1c03d34b/src/sql/types/value.rs#L40-L64
 
-The `Value` type provides basic formatting, conversion, and mathematical operations. It also
-specifies comparison and ordering semantics, but these are subtly different from the SQL semantics.
-For example, in Rust code `Value::Null == Value::Null` yields `true`, while in SQL `NULL = NULL`
-yields `NULL`.  This mismatch is necessary for the Rust code to properly detect and process `Null`
-values, and the desired SQL semantics are implemented higher up in the SQL execution engine (we'll
-get back to this later).
+The `Value` type provides basic formatting, conversion, and mathematical operations.
+
+https://github.com/erikgrinaker/toydb/blob/686d3971a253bfc9facc2ba1b0e716cff5c109fb/src/sql/types/value.rs#L68-L79
+
+https://github.com/erikgrinaker/toydb/blob/686d3971a253bfc9facc2ba1b0e716cff5c109fb/src/sql/types/value.rs#L164-L370
+
+It also specifies comparison and ordering semantics, but these are subtly different from the SQL
+semantics. For example, in Rust code `Value::Null == Value::Null` yields `true`, while in SQL
+`NULL = NULL` yields `NULL`.  This mismatch is necessary for the Rust code to properly detect and
+process `Null` values, and the desired SQL semantics are implemented during expression evaluation
+which we'll cover below.
 
 https://github.com/erikgrinaker/toydb/blob/b2fe7b76ee634ca6ad31616becabfddb1c03d34b/src/sql/types/value.rs#L91-L162
 
-During execution, a row of values will be represented as `sql::types::Row`, with multiple rows
-emitted as `sql::types::Rows` row iterators:
+During execution, a row of values is represented as `sql::types::Row`, with multiple rows emitted
+via `sql::types::Rows` row iterators:
 
 https://github.com/erikgrinaker/toydb/blob/b2fe7b76ee634ca6ad31616becabfddb1c03d34b/src/sql/types/value.rs#L378-L388
 
 ## Schemas
 
-toyDB schemas support a single object: a table. There's only a single, unnamed database, and no
-named indexes, constraints, or other schema objects.
+toyDB schemas only support tables. There are no named indexes or constraints, and there's only a
+single unnamed database.
 
 Tables are represented by `sql::types::Table`:
 
@@ -47,42 +54,41 @@ The table name serves as a unique identifier, and can't be changed later. In fac
 are entirely static: they can only be created or dropped (there are no schema changes).
 
 Table schemas are stored in the catalog, represented by the `sql::engine::Catalog` trait. We'll
-revisit the implementation of this trait in the storage section below.
+revisit the implementation of this trait in the SQL storage section.
 
 https://github.com/erikgrinaker/toydb/blob/0839215770e31f1e693d5cccf20a68210deaaa3f/src/sql/engine/engine.rs#L60-L79
 
-Table schemas are validated (e.g. during creation) via the `Table::validate()` method, which
-enforces invariants and internal consistency. It uses the catalog to look up information about other
-tables, e.g. that foreign key references point to a valid target column.
+Table schemas are validated when created via `Table::validate()`, which enforces invariants and
+internal consistency. It uses the catalog to look up information about other tables, e.g. that
+foreign key references point to a valid target column in a different table.
 
 https://github.com/erikgrinaker/toydb/blob/c2b0f7f1d6cbf6e2cdc09fc0aec7b050e840ec21/src/sql/types/schema.rs#L98-L170
 
-It also has a `Table::validate_row()` method which is used to validate that a given
-`sql::types::Row` conforms to the schema (e.g. that the value data types match the column data
-types). It uses a `sql::engine::Transaction` to look up other rows in the database, e.g. to check
-for primary key conflicts (we'll get back to this below).
+Table rows are validated via `Table::validate_row()`, which ensures that a `sql::types::Row`
+conforms to the schema (e.g. that value types match the column data types). It uses a
+`sql::engine::Transaction` to look up other rows in the database, e.g. to check for primary key
+conflicts (we'll get back to this later).
 
 https://github.com/erikgrinaker/toydb/blob/c2b0f7f1d6cbf6e2cdc09fc0aec7b050e840ec21/src/sql/types/schema.rs#L172-L236
 
 ## Expressions
 
 During SQL execution, we also have to model _expressions_, such as `1 + 2 * 3`. These are
-represented as values and operations on them. They can be nested arbitrarily as a tree to represent
-compound operations.
+represented as values and operations on them, and can be nested as a tree to represent compound
+operations.
 
 https://github.com/erikgrinaker/toydb/blob/9419bcf6aededf0e20b4e7485e2a5fa3e975d79f/src/sql/types/expression.rs#L11-L64
 
 
-For example:
+For example, the expression `1 + 2 * 3` (taking [precedence](https://en.wikipedia.org/wiki/Order_of_operations)
+into account) is represented as:
 
 ```rust
-// 1 + 2 * 3 is represented as:
-//
-//             +
-//            / \
-//           1   *
-//              /  \
-///            2    3
+//    +
+//   / \
+//  1   *
+//     /  \
+///   2    3
 Expression::Add(
     Expression::Constant(Value::Integer(1)),
     Expression::Multiply(
@@ -97,8 +103,8 @@ An `Expression` can contain two kinds of values: constant values as
 references. The latter will fetch a `sql::types::Value` from a `sql::types::Row` at the specified
 index during evaluation.
 
-We'll see later how the SQL parser and planner transforms text expressions like `1 + 2 * 3` into
-this `Expression` form, and how it resolves column names to row indexes -- e.g. `price * 0.25` to
+We'll see later how the SQL parser and planner transforms text expression like `1 + 2 * 3` into an
+`Expression`, and how it resolves column names to row indexes like `price * 0.25` to
 `row[3] * 0.25`.
 
 Expressions are evaluated recursively via `Expression::evalute()`, given a `sql::types::Row` with