clarify docs some more

crates/fayalite/src/_docs/modules/module_bodies/hdl_array_expressions.rs

@@ -1,6 +1,6 @@
 //! # `#[hdl]` Array Expressions
 //!
-//! `#[hdl]` can be used on Array Expressions to construct an [`Array<[T; N]>`][Array] value:
+//! `#[hdl]` can be used on Array Expressions to construct an [`Array<[T; N]>`][Array] expression:
 //!
 //! ```
 //! # use fayalite::{hdl_module, int::UInt, array::Array};
@@ -22,6 +22,8 @@
 //! );
 //! # }
 //! ```
+//!
+//! `#[hdl] [...]` expressions have type [`Expr<Array<[T; N]>>`][Expr]
 
 #[allow(unused)]
-use crate::array::Array;
+use crate::{array::Array, expr::Expr};

crates/fayalite/src/_docs/modules/module_bodies/hdl_if_statements.rs

@@ -3,9 +3,18 @@
 //! `#[hdl] if` statements behave similarly to Rust `if` statements, except they end up as muxes
 //! and stuff in the final hardware instead of being run when the fayalite module is being created.
 //!
+//! The condition of an `#[hdl] if` statement must have type [`UInt<1>`] or [`DynUInt`] with
+//! `width() == 1` or be an [expression][Expr] of one of those types.
+//!
 //! `#[hdl] if` statements' bodies must evaluate to type `()` for now.
 //!
-//! You can use `if`, `else`, `else if`, `if let`, and `else if let` as usual, with the `if let`
-//! variants behaving like [`#[hdl] match`][match].
+//! You can use `if`, `else`, `else if`, `if let`, and `else if let` as usual, with the
+//! `[else] if let` variants behaving like [`#[hdl] match`][match].
 //!
 //! [match]: super::hdl_match_statements
+
+#[allow(unused)]
+use crate::{
+    expr::Expr,
+    int::{DynUInt, UInt},
+};

crates/fayalite/src/_docs/modules/module_bodies/hdl_let_statements/inputs_outputs.rs

@@ -1,5 +1,7 @@
 //! ### Inputs/Outputs
 //!
+//! Inputs/Outputs create a Rust variable with type [`Expr<T>`] where `T` is the type of the input/output.
+//!
 //! Inputs/Outputs follow [connection semantics], which are unlike assignments in software,
 //! so you should read it.
 //!
@@ -16,3 +18,6 @@
 //! ```
 //!
 //! [connection semantics]: crate::_docs::semantics::connection_semantics
+
+#[allow(unused)]
+use crate::expr::Expr;

crates/fayalite/src/_docs/modules/module_bodies/hdl_let_statements/registers.rs

@@ -3,6 +3,8 @@
 //! Registers are memory devices that will change their state only on a clock
 //! edge (or when being reset). They retain their state when not connected to.
 //!
+//! Registers create a Rust variable with type [`Expr<T>`] where `T` is the type of the register.
+//!
 //! Registers follow [connection semantics], which are unlike assignments in software, so you should read it.
 //!
 //! ```
@@ -23,3 +25,6 @@
 //! ```
 //!
 //! [connection semantics]: crate::_docs::semantics::connection_semantics
+
+#[allow(unused)]
+use crate::expr::Expr;

crates/fayalite/src/_docs/modules/module_bodies/hdl_let_statements/wires.rs

@@ -4,6 +4,8 @@
 //! they have no memory (they're combinatorial).
 //! You must [connect][`ModuleBuilder::connect`] to all wires, so they have a defined value.
 //!
+//! Registers create a Rust variable with type [`Expr<T>`] where `T` is the type of the register.
+//!
 //! Wires follow [connection semantics], which are unlike assignments in software, so you should read it.
 //!
 //! ```
@@ -26,4 +28,4 @@
 //! [connection semantics]: crate::_docs::semantics::connection_semantics
 
 #[allow(unused)]
-use crate::module::ModuleBuilder;
+use crate::{expr::Expr, module::ModuleBuilder};

crates/fayalite/src/_docs/modules/module_bodies/hdl_literals.rs

@@ -2,6 +2,9 @@
 //!
 //! You can have integer literals with an arbitrary number of bits like so:
 //!
+//! `_hdl`-suffixed literals have type [`Expr<UInt<N>>`] or [`Expr<SInt<N>>`]
+//! ... which are basically just [`UInt<N>`] or [`SInt<N>`] converted to an expression.
+//!
 //! ```
 //! # #[fayalite::hdl_module]
 //! # fn module() {
@@ -15,3 +18,9 @@
 //! let empty = 0_hdl_u0; // a UInt<0>
 //! # }
 //! ```
+
+#[allow(unused)]
+use crate::{
+    expr::Expr,
+    int::{SInt, UInt},
+};