write docs for #[hdl] expressions

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

@@ -3,6 +3,9 @@
 //! The `#[hdl_module]` attribute lets you have statements/expressions with `#[hdl]` annotations
 //! and `_hdl`-suffixed literals in the module function's body
 
+pub mod hdl_array_expressions;
 pub mod hdl_if_statements;
 pub mod hdl_let_statements;
 pub mod hdl_literals;
+pub mod hdl_match_statements;
+pub mod hdl_struct_variant_expressions;

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

@@ -0,0 +1,27 @@
+//! # `#[hdl]` Array Expressions
+//!
+//! `#[hdl]` can be used on Array Expressions to construct an [`Array<[T; N]>`][Array] value:
+//!
+//! ```
+//! # use fayalite::{hdl_module, int::UInt, array::Array};
+//! # #[hdl_module]
+//! # fn module() {
+//! #[hdl]
+//! let v: UInt<8> = m.input();
+//! #[hdl]
+//! let w: Array<[UInt<8>; 4]> = m.wire();
+//! m.connect(
+//!     w,
+//!     #[hdl]
+//!     [4_hdl_u8, v, 3_hdl_u8, v + 7_hdl_u8] // you can make an array like this
+//! );
+//! m.connect(
+//!     w,
+//!     #[hdl]
+//!     [v + 1_hdl_u8; 4] // or you can make an array repeat like this
+//! );
+//! # }
+//! ```
+
+#[allow(unused)]
+use crate::array::Array;

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

@@ -1,3 +1,11 @@
 //! # `#[hdl] if` Statements
 //!
-//! FIXME
+//! `#[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.
+//!
+//! `#[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].
+//!
+//! [match]: super::hdl_match_statements

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

@@ -0,0 +1,9 @@
+//! # `#[hdl] match` Statements
+//!
+//! `#[hdl] match` statements behave similarly to Rust `match` statements, except they end up as muxes
+//! and stuff in the final hardware instead of being run when the fayalite module is being created.
+//!
+//! `#[hdl] match` statements' bodies must evaluate to type `()` for now.
+//!
+//! `#[hdl] match` statements can only match one level of struct/enum pattern for now,
+//! e.g. you can match with the pattern `Some(v)`, but not `Some(Some(_))`.

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

@@ -0,0 +1,59 @@
+//! # `#[hdl]` Struct/Variant Expressions
+//!
+//! Note: Structs are also known as [Bundles] when used in Fayalite, the Bundle name comes from [FIRRTL].
+//!
+//! [Bundles]: crate::bundle::BundleValue
+//! [FIRRTL]: https://github.com/chipsalliance/firrtl-spec
+//!
+//! `#[hdl]` can be used on Struct/Variant Expressions to construct a value of that
+//! struct/variant's type. They can also be used on tuples.
+//!
+//! ```
+//! # use fayalite::{hdl_module, int::UInt, array::Array, ty::Value};
+//! #[derive(Value, Clone, PartialEq, Eq, Hash, Debug)]
+//! pub struct MyStruct {
+//!     pub a: UInt<8>,
+//!     pub b: UInt<16>,
+//! }
+//!
+//! #[derive(Value, Clone, PartialEq, Eq, Hash, Debug)]
+//! pub enum MyEnum {
+//!     A,
+//!     B {
+//!         v: UInt<32>,
+//!     },
+//! }
+//!
+//! # #[hdl_module]
+//! # fn module() {
+//! #[hdl]
+//! let v: UInt<8> = m.input();
+//! #[hdl]
+//! let my_struct: MyStruct = m.wire();
+//! m.connect(
+//!     my_struct,
+//!     #[hdl]
+//!     MyStruct {
+//!         a: v,
+//!         b: 1234_hdl_u16,
+//!     },
+//! );
+//! #[hdl]
+//! let my_enum: MyEnum = m.wire();
+//! m.connect(
+//!     my_enum,
+//!     #[hdl]
+//!     MyEnum::B { v: 12345678_hdl_u32 },
+//! );
+//! #[hdl]
+//! let some_tuple: (UInt<4>, UInt<12>) = m.wire();
+//! m.connect(
+//!     some_tuple,
+//!     #[hdl]
+//!     (12_hdl_u4, 3421_hdl_u12),
+//! );
+//! # }
+//! ```
+
+#[allow(unused)]
+use crate::array::Array;