AI-generate implementation documentation (#247)

* Scaffold initial implementation docs

* Generate remaining impl docs

* Use bullet points for source and tests sections

Author: soareschen

crates/macros/cgp-macro-core/CLAUDE.md

@@ -78,3 +78,13 @@ into the existing stage rather than collapsing the pipeline.
 
 **5. Custom keywords go through `define_keyword!` + `IsKeyword`** (see
 [src/macros/keyword.rs](src/macros/keyword.rs) and `types/keyword*.rs`).
+
+**6. Keep inline docs brief and current as you go.** When you review a file — whether to change it
+or to write its [implementation document](../../../docs/implementation/README.md) — improve the
+inline docs in the same pass. Add a one-line `///` to any public struct, trait, or function that
+lacks one, saying what it is or does (for a pipeline stage, its role in the sequence); prefer naming
+the *why* or a corner case over restating the signature. Fix a doc that no longer matches the code,
+and clarify genuinely confusing code (for example, why `generic_params_to_path` keeps only type
+parameters) with a short comment. Keep them terse: delete a comment that only restates obvious code,
+and do not narrate line by line. Deep mechanics belong in the implementation document, not in a wall
+of inline prose — link to it rather than duplicating it.

crates/macros/cgp-macro-core/src/functions/delegated_impls/provider_trait.rs

@@ -3,6 +3,8 @@ use syn::{ImplItem, ItemTrait, Type};
 use crate::functions::trait_items_to_delegated_impl_items;
 use crate::parse_internal;
 
+/// Forward a provider trait's own items to `delegate_type`, reconstructing the
+/// trait path from the trait itself (for impls whose trait *is* the provider trait).
 pub fn provider_trait_to_impl_items(
     item_trait: &ItemTrait,
     delegate_type: &Type,

crates/macros/cgp-macro-core/src/functions/delegated_impls/trait_items.rs

@@ -7,6 +7,8 @@ use crate::functions::{
     parse_internal, signature_to_delegated_impl_item_fn, trait_to_impl_item_type,
 };
 
+/// Build impl items that forward each trait item (method, associated type, or
+/// const) to `delegate_type`, projecting types/consts through `provider_trait_path`.
 pub fn trait_items_to_delegated_impl_items(
     trait_items: &[TraitItem],
     delegate_type: &Type,

crates/macros/cgp-macro-core/src/functions/is_provider_params.rs

@@ -6,6 +6,11 @@ use crate::exports::Life;
 use crate::parse_internal;
 use crate::types::generics::TypeGenerics;
 
+/// Convert a trait's generics into the `Params` tuple types of an `IsProviderFor`
+/// bound: type params pass through, lifetimes are lifted into `Life<'a>`.
+///
+/// Panics on a const generic parameter — see the const-generic limitation in
+/// docs/implementation/entrypoints/cgp_component.md.
 pub fn parse_is_provider_params(generics: &Generics) -> syn::Result<Punctuated<Type, Comma>> {
     let params = TypeGenerics::try_from(generics)?.generics.params;
 

crates/macros/cgp-macro-core/src/functions/parse_internal.rs

@@ -8,6 +8,9 @@ use syn::{Error, parse2};
 use crate::functions::strip_macro_prelude;
 pub use crate::macros::parse_internal;
 
+/// Parse a token stream into a `syn` type `T`, attaching an error that names both
+/// `T` and the offending tokens (prelude prefix stripped) on failure. Usually
+/// invoked through the `parse_internal!` macro.
 pub fn parse_internal<T>(body: TokenStream) -> Result<T, Error>
 where
     T: Parse,

crates/macros/cgp-macro-core/src/macros/keyword.rs

@@ -1,3 +1,5 @@
+/// Declare a custom-keyword marker: a zero-sized struct plus its `IsKeyword` impl
+/// carrying the keyword's spelling, which the parsers peek against.
 #[macro_export]
 macro_rules! define_keyword {
     ( $struct_ident:ident, $value:literal ) => {

crates/macros/cgp-macro-core/src/macros/parse.rs

@@ -1,3 +1,6 @@
+/// Quasi-quote tokens and parse them into an inferred `syn` type via the
+/// `parse_internal` function. Expands to a `?` expression, so it must be called
+/// inside a `syn::Result`-returning function.
 #[macro_export]
 macro_rules! parse_internal {
     ( $($body:tt)* ) => {

crates/macros/cgp-macro-core/src/types/cgp_component/args/component_args.rs

@@ -5,6 +5,9 @@ use syn::{Error, Ident};
 use crate::types::cgp_component::CgpComponentRawArgs;
 use crate::types::ident::IdentWithTypeGenerics;
 
+/// The `#[cgp_component]` attribute args with defaults applied: the context type
+/// identifier (`__Context__` by default), the required provider trait name, and
+/// the component marker name (`{Provider}Component` by default).
 #[derive(Clone)]
 pub struct CgpComponentArgs {
     pub context_ident: Ident,

crates/macros/cgp-macro-core/src/types/cgp_component/args/raw.rs

@@ -4,6 +4,9 @@ use syn::{Error, Ident};
 
 use crate::types::ident::IdentWithTypeGenerics;
 
+/// The attribute args exactly as written, before defaults are applied. Parses
+/// either a bare provider identifier or the `key: value` form; [`CgpComponentArgs`]
+/// resolves the defaults via `TryFrom`.
 #[derive(Default)]
 pub struct CgpComponentRawArgs {
     pub context_ident: Option<Ident>,

crates/macros/cgp-macro-core/src/types/cgp_component/evaluated/item.rs

@@ -5,6 +5,9 @@ use crate::types::cgp_component::CgpComponentArgs;
 use crate::types::empty_struct::EmptyStruct;
 use crate::types::provider_impl::{ItemProviderImpl, ItemProviderImpls};
 
+/// Final pipeline stage: all derived items, plus the args and attributes needed
+/// to render the standard provider impls (`UseContext`, `RedirectLookup`, and the
+/// per-attribute `UseDelegate`/prefix impls).
 pub struct EvaluatedCgpComponent {
     pub component_struct: EmptyStruct,
     pub consumer_trait: ItemTrait,
@@ -16,6 +19,8 @@ pub struct EvaluatedCgpComponent {
 }
 
 impl EvaluatedCgpComponent {
+    /// Emit the five core items in fixed order (consumer trait, consumer impl,
+    /// provider trait, provider impl, marker struct), then the provider impls.
     pub fn to_items(&self) -> syn::Result<Vec<Item>> {
         let mut items = vec![
             Item::Trait(self.consumer_trait.clone()),
@@ -55,6 +60,7 @@ impl EvaluatedCgpComponent {
         Ok(provider_impls)
     }
 
+    /// One `UseDelegate` provider impl per `#[derive_delegate]` attribute.
     pub fn to_use_delegate_impls(&self) -> syn::Result<ItemProviderImpls> {
         let provider_trait = &self.provider_trait;
         let component_type = self.args.component_name.to_type();
@@ -71,6 +77,7 @@ impl EvaluatedCgpComponent {
         Ok(provider_impls)
     }
 
+    /// One namespace prefix impl per `#[prefix]` attribute (from `#[cgp_namespace]`).
     pub fn to_prefix_impls(&self) -> syn::Result<Vec<ItemImpl>> {
         let component_name = &self.args.component_name;
         let mut provider_impls = Vec::new();