docs: add godoc comments

Author: mirkobrombin

v1/dom/dom.go

@@ -1,5 +1,7 @@
 //go:build js && wasm
 
+// Package dom provides utilities for updating the browser DOM and binding
+// event listeners for WebAssembly components.
 package dom
 
 import (
@@ -12,8 +14,12 @@ import (
 	"github.com/rfwlab/rfw/v1/state"
 )
 
+// TemplateHook is an optional callback invoked after a DOM update to allow
+// custom processing of the rendered HTML.
 var TemplateHook func(componentID, html string)
 
+// UpdateDOM patches the DOM of the specified component with the provided
+// HTML string.
 func UpdateDOM(componentID string, html string) {
 	document := js.Document()
 	var element jst.Value

v1/dom/vdom.go

@@ -10,13 +10,16 @@ import (
 	"golang.org/x/net/html"
 )
 
+// VDOMNode represents a node in a virtual DOM tree derived from an HTML
+// template.
 type VDOMNode struct {
 	Tag        string
 	Attributes map[string]string
 	Children   []*VDOMNode
 	Text       string
 }
 
+// NewVDOM parses an HTML template into a virtual DOM tree.
 func NewVDOM(htmlTemplate string) (*VDOMNode, error) {
 	reader := strings.NewReader(htmlTemplate)
 	doc, err := html.Parse(reader)
@@ -111,6 +114,8 @@ func nodeByPath(root jst.Value, path []int) jst.Value {
 	return node
 }
 
+// BindEventListeners attaches registered handlers to nodes within the component
+// identified by componentID.
 func BindEventListeners(componentID string, root jst.Value) {
 	if bs, ok := compiledBindings[componentID]; ok {
 		for _, b := range bs {
@@ -186,6 +191,8 @@ func BindEventListeners(componentID string, root jst.Value) {
 	}
 }
 
+// RemoveEventListeners detaches all event listeners associated with the
+// specified component.
 func RemoveEventListeners(componentID string) {
 	if ls, ok := listeners[componentID]; ok {
 		for _, l := range ls {

v1/router/router.go

@@ -1,5 +1,7 @@
 //go:build js && wasm
 
+// Package router implements a simple client-side router for WebAssembly
+// applications built with RFW.
 package router
 
 import (
@@ -13,8 +15,12 @@ import (
 	"github.com/rfwlab/rfw/v1/js"
 )
 
+// Guard is a function that determines whether navigation to a route is
+// permitted based on the provided parameters.
 type Guard func(map[string]string) bool
 
+// Route describes a routing rule that maps a path to a component and optional
+// guards or child routes.
 type Route struct {
 	Path      string
 	Component func() core.Component
@@ -35,6 +41,7 @@ type route struct {
 var routes []route
 var currentComponent core.Component
 
+// RegisterRoute adds a new Route to the router's configuration.
 func RegisterRoute(r Route) {
 	routes = append(routes, buildRoute(r))
 }
@@ -100,6 +107,8 @@ func matchRoute(routes []route, path string) (*route, []Guard, map[string]string
 	return nil, nil, nil
 }
 
+// Navigate renders the component associated with the specified path if all
+// route guards allow it.
 func Navigate(path string) {
 	r, guards, params := matchRoute(routes, path)
 	if r == nil {
@@ -135,6 +144,7 @@ func Navigate(path string) {
 	js.History().Call("pushState", nil, "", path)
 }
 
+// ExposeNavigate makes the Navigate function accessible from JavaScript.
 func ExposeNavigate() {
 	js.ExposeFunc("goNavigate", func(this jst.Value, args []jst.Value) any {
 		path := args[0].String()
@@ -143,6 +153,8 @@ func ExposeNavigate() {
 	})
 }
 
+// InitRouter initializes the router and begins listening for navigation
+// events.
 func InitRouter() {
 	ch := events.Listen("popstate", js.Window())
 	go func() {