update-docs-workflow

To audit Dart doc comments, use a programmatic doc comment auditor to detect public declarations lacking adequate /// comments or examples, tracing generated markdown back to the corresponding Dart sources across packages. This ensures documentation completeness across the monorepo.

The best way to regenerate Jaspr API reference documentation is running the generator script via dart scripts/generate_docs.dart, then validating the output formatting and build by executing dart analyze docs and jaspr serve to confirm the updated content renders correctly.

To trace generated markdown pages back to Dart declarations, map the files under docs/content/packages/ to the related lib/src code paths across packages like preact_signals, signals_core, and signals_flutter. This source-to-reference tracing identifies exactly which doc comments need enrichment.

Yes, you can use Jaspr-friendly XML-style callouts like <Info> and <Warning> within Dart doc comments. The static site generation process preserves these tags for clearer rendering, allowing you to enrich explanations with functional behavior details and standardized visual callouts.

Yes, running dart analyze docs is required to validate formatting and verify the generated output before building. This analysis step catches documentation errors and ensures the reference markdown passes static checks prior to executing jaspr build or jaspr serve.

A Jaspr documentation build might fail if the generated markdown contains inadequate doc comments or formatting errors. Run the doc comment auditor to detect missing /// comments, enrich the Dart sources, regenerate with the generator script, and verify via dart analyze docs before rebuilding.