From 1958cc79b1d36aeabd403b32f4aed65f6a291831 Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Fri, 3 Apr 2026 18:53:50 +0000
Subject: [PATCH] docs(html): align public API docs with AX principles

Co-Authored-By: Virgil <virgil@lethean.io>
---
 codegen/codegen.go | 10 +++++-----
 layout.go          | 15 ++++++++++-----
 node.go            |  3 ++-
 3 files changed, 17 insertions(+), 11 deletions(-)

diff --git a/codegen/codegen.go b/codegen/codegen.go
index 599cc27..4ea31ba 100644
--- a/codegen/codegen.go
+++ b/codegen/codegen.go
@@ -56,7 +56,7 @@ var wcTemplate = template.Must(template.New("wc").Parse(`class {{.ClassName}} ex
   }
 }`))
 
-// GenerateClass produces a JS class definition for a custom element.
+// codegen/codegen.go: GenerateClass produces a JS class definition for a custom element.
 //
 //	cls, err := GenerateClass("nav-bar", "H")
 func GenerateClass(tag, slot string) (string, error) {
@@ -77,14 +77,14 @@ func GenerateClass(tag, slot string) (string, error) {
 	return b.String(), nil
 }
 
-// GenerateRegistration produces the customElements.define() call.
+// codegen/codegen.go: GenerateRegistration produces the customElements.define() call.
 //
 //	js := GenerateRegistration("nav-bar", "NavBar")
 func GenerateRegistration(tag, className string) string {
 	return fmt.Sprintf(`customElements.define("%s", %s);`, tag, className)
 }
 
-// TagToClassName converts a kebab-case tag to PascalCase class name.
+// codegen/codegen.go: TagToClassName converts a kebab-case tag to PascalCase class name.
 //
 //	className := TagToClassName("nav-bar") // NavBar
 func TagToClassName(tag string) string {
@@ -98,7 +98,7 @@ func TagToClassName(tag string) string {
 	return b.String()
 }
 
-// GenerateBundle produces all WC class definitions and registrations
+// codegen/codegen.go: GenerateBundle produces all WC class definitions and registrations
 // for a set of HLCRF slot assignments.
 //
 //	js, err := GenerateBundle(map[string]string{"H":"nav-bar", "C":"main-content"})
@@ -118,7 +118,7 @@ func GenerateBundle(slots map[string]string) (string, error) {
 	return b.String(), nil
 }
 
-// GenerateTypeDefinitions produces a TypeScript declaration file for the
+// codegen/codegen.go: GenerateTypeDefinitions produces a TypeScript declaration file for the
 // generated custom elements.
 //
 //	dts, err := GenerateTypeDefinitions(map[string]string{"H":"nav-bar"})
diff --git a/layout.go b/layout.go
index 3041a7f..0fb6b11 100644
--- a/layout.go
+++ b/layout.go
@@ -71,31 +71,36 @@ func ValidateLayoutVariant(variant string) error {
 	return &layoutVariantError{variant: variant, invalidSlots: invalidSlots}
 }
 
-// H appends nodes to the Header slot.
+// layout.go: H appends nodes to the Header slot.
+// Example: NewLayout("HCF").H(Raw("head")).
 func (l *Layout) H(nodes ...Node) *Layout {
 	l.slots['H'] = append(l.slots['H'], nodes...)
 	return l
 }
 
-// L appends nodes to the Left aside slot.
+// layout.go: L appends nodes to the Left aside slot.
+// Example: NewLayout("HLCRF").L(Raw("nav")).
 func (l *Layout) L(nodes ...Node) *Layout {
 	l.slots['L'] = append(l.slots['L'], nodes...)
 	return l
 }
 
-// C appends nodes to the Content (main) slot.
+// layout.go: C appends nodes to the Content (main) slot.
+// Example: NewLayout("C").C(Raw("body")).
 func (l *Layout) C(nodes ...Node) *Layout {
 	l.slots['C'] = append(l.slots['C'], nodes...)
 	return l
 }
 
-// R appends nodes to the Right aside slot.
+// layout.go: R appends nodes to the Right aside slot.
+// Example: NewLayout("HLCRF").R(Raw("aside")).
 func (l *Layout) R(nodes ...Node) *Layout {
 	l.slots['R'] = append(l.slots['R'], nodes...)
 	return l
 }
 
-// F appends nodes to the Footer slot.
+// layout.go: F appends nodes to the Footer slot.
+// Example: NewLayout("HCF").F(Raw("foot")).
 func (l *Layout) F(nodes ...Node) *Layout {
 	l.slots['F'] = append(l.slots['F'], nodes...)
 	return l
diff --git a/node.go b/node.go
index 95116b4..2587011 100644
--- a/node.go
+++ b/node.go
@@ -267,8 +267,9 @@ func Alt(n Node, text string) Node {
 	return Attr(n, "alt", text)
 }
 
-// node.go: AltText sets the alt attribute on an element node.
+// node.go: AltText is a compatibility alias for Alt.
 // Example: AltText(El("img"), "Product screenshot").
+// Prefer Alt for new call sites so the canonical image helper stays predictable.
 func AltText(n Node, text string) Node {
 	return Alt(n, text)
 }