From 4b24a886413da316e71bf8f61ce091bbde73b1ab Mon Sep 17 00:00:00 2001
From: Jacob Lifshay <programmerjake@gmail.com>
Date: Sun, 26 Oct 2025 03:01:26 -0700
Subject: [PATCH] add docs for #[hdl] and particularly for #[hdl] type aliases

---
 crates/fayalite/src/lib.rs | 129 +++++++++++++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)

diff --git a/crates/fayalite/src/lib.rs b/crates/fayalite/src/lib.rs
index 7998e6f..98849a6 100644
--- a/crates/fayalite/src/lib.rs
+++ b/crates/fayalite/src/lib.rs
@@ -86,6 +86,135 @@ macro_rules! __cfg_expansion_helper {
 pub use fayalite_proc_macros::hdl_module;
 
 #[doc(inline)]
+/// The `#[hdl]` attribute is supported on several different kinds of [Rust Items](https://doc.rust-lang.org/reference/items.html):
+///
+/// # Functions and Methods
+/// Enable's the stuff that you can use inside a [module's body](crate::_docs::modules::module_bodies),
+/// but without being a module or changing the function's signature.
+/// The only exception is that you can't use stuff that requires the automatically-provided `m` variable.
+///
+/// # Structs
+// TODO: expand on struct docs
+/// e.g.:
+/// ```
+/// # use fayalite::prelude::*;
+/// # #[hdl]
+/// # pub struct OtherStruct {}
+/// #[hdl]
+/// pub struct MyStruct {
+///     #[hdl(flip)]
+///     pub a: UInt<5>,
+///     pub b: Bool,
+///     #[hdl(flip)]
+///     pub c: OtherStruct,
+/// }
+/// ```
+///
+/// # Enums
+// TODO: expand on enum docs
+/// e.g.:
+/// ```
+/// # use fayalite::prelude::*;
+/// # #[hdl]
+/// # pub struct MyStruct {}
+/// #[hdl]
+/// pub enum MyEnum {
+///     A(UInt<3>),
+///     B,
+///     C(MyStruct),
+/// }
+/// ```
+///
+/// # Type Aliases
+///
+/// There's three different ways you can create a type alias:
+///
+/// # Normal Type Alias
+///
+/// This works exactly how you'd expect:
+/// ```
+/// # use fayalite::prelude::*;
+/// # #[hdl]
+/// # pub struct MyStruct<T: Type> {
+/// #     v: T,
+/// # }
+/// #[hdl]
+/// pub type MyType<T: Type> = MyStruct<T>;
+///
+/// // you can then use Fayalite's standard syntax for creating dynamic types at runtime:
+///
+/// let ty = MyType[UInt[3]];
+/// assert_eq!(ty, MyStruct[UInt[3]]);
+/// ```
+///
+/// # Type Alias that gets a [`Type`] from a [`PhantomConst`]
+///
+/// This allows you to use some computed property of a [`PhantomConst`] to get a [`Type`] that you can use in other #[hdl] types.
+///
+/// ```
+/// # use fayalite::{intern::Intern, prelude::*};
+/// #[derive(Clone, PartialEq, Eq, Hash, Debug, serde::Serialize, serde::Deserialize)]
+/// pub struct Config {
+///     pub foo: usize,
+///     pub bar: Bundle,
+/// }
+///
+/// // the expression inside `get` is called with `Interned<Config>` and returns `Array<Bundle>`
+/// #[hdl(get(|config| Array[config.bar][config.foo]))]
+/// pub type GetMyArray<P: PhantomConstGet<Config>> = Array<Bundle>;
+///
+/// // you can then use it in other types:
+///
+/// #[hdl(no_static)]
+/// pub struct WrapMyArray<P: Type + PhantomConstGet<Config>> {
+///     pub my_array: GetMyArray<P>,
+/// }
+///
+/// // you can then use Fayalite's standard syntax for creating dynamic types at runtime:
+/// let bar = Bundle::new(Default::default());
+/// let config = PhantomConst::new(Config { foo: 12, bar }.intern_sized());
+/// let ty = WrapMyArray[config];
+/// assert_eq!(ty.my_array, Array[bar][12]);
+/// ```
+///
+/// # Type Alias that gets a [`Size`] from a [`PhantomConst`]
+///
+/// This allows you to use some computed property of a [`PhantomConst`] to get a [`Size`] that you can use in other #[hdl] types.
+///
+/// ```
+/// # use fayalite::{intern::Intern, prelude::*};
+/// # #[derive(Clone, PartialEq, Eq, Hash, Debug, serde::Serialize, serde::Deserialize)]
+/// # pub struct ConfigItem {}
+/// # impl ConfigItem {
+/// #     pub fn new() -> Self {
+/// #         Self {}
+/// #     }
+/// # }
+/// #[derive(Clone, PartialEq, Eq, Hash, Debug, serde::Serialize, serde::Deserialize)]
+/// pub struct Config {
+///     pub items: Vec<ConfigItem>,
+/// }
+///
+/// // the expression inside `get` is called with `Interned<Config>` and returns `usize` (not DynSize)
+/// #[hdl(get(|config| config.items.len()))]
+/// pub type GetItemsLen<P: PhantomConstGet<Config>> = DynSize; // must be DynSize
+///
+/// // you can then use it in other types:
+///
+/// #[hdl(no_static)]
+/// pub struct FlagPerItem<P: Type + PhantomConstGet<Config>> {
+///     pub flags: ArrayType<Bool, GetItemsLen<P>>,
+/// }
+///
+/// // you can then use Fayalite's standard syntax for creating dynamic types at runtime:
+/// let config = PhantomConst::new(Config { items: vec![ConfigItem::new(); 5] }.intern_sized());
+/// let ty = FlagPerItem[config];
+/// assert_eq!(ty.flags, Array[Bool][5]);
+/// ```
+///
+/// [`PhantomConst`]: crate::phantom_const::PhantomConst
+/// [`Size`]: crate::int::Size
+/// [`Type`]: crate::ty::Type
 pub use fayalite_proc_macros::hdl;
 
 pub use bitvec;