javascript-doxygen

Imported from wesley-dean/javascript-doxygen (AGENTS.md). Install upstream with npx skills add wesley-dean/javascript-doxygen. Copyright stays with the author.

AGENTS.md

Repository Purpose

javascript-doxygen provides a documentation-led Doxygen input filter for JavaScript. Maintained JavaScript should remain idiomatic JavaScript; translation belongs at the Doxygen boundary rather than in a second maintained documentation dialect.

The maintained filter is doxygen-javascript.awk.

The current implementation translates the accepted simple-parameter JSDoc forms governed by ADR-013 and ADR-014, canonical typed @returns records governed by ADR-016, canonical typed-and-described @throws records governed by ADR-017, canonical typed @yields records governed by ADR-019, canonical virtual @typedef records governed by ADR-021, canonical child @property records governed by ADR-022, and canonical named @callback contracts governed by ADR-023. ADR-018 exercises governed forms through Doxygen's JavaScript parser, ADR-020 establishes native-compatible pass-through for proven @deprecated and @see forms, ADR-024 establishes consumer-alias rendering for byte-preserved canonical @type annotations, ADR-025 establishes generated development, ordinary, and minified AWK build artifacts with adjacent SHA-256 files, ADR-026 governs semantic-version publication of those exact artifacts plus post-publication canary evidence, and ADR-027 normalizes generated, released, and vendored artifact names to the sibling doxygen-<language>.awk convention. Unsupported JSDoc constructs remain visible unchanged. Do not claim broader JSDoc translation, native compatibility, consumer-alias support, JavaScript semantic analysis, or release behavior beyond the accepted governance and executable evidence.

Governing Documentation

Before changing the repository, review README.md, this file, the applicable files under doc/standards/, every ADR in doc/adr/*.md, and doc/decisions.md.

Accepted ADRs are governance. Consequential parser, interface, portability, compatibility, documentation-publication, integration, consumer-configuration, virtual-type representation, build/distribution, or release changes require an ADR unless existing governance already covers the decision.

Files under doc/standards/ are governing project requirements when applicable. General and cross-cutting standards apply where relevant; language-specific standards apply only to maintained content in that language. Presence in the complete released snapshot does not by itself make a standard applicable. Content beneath doc/standards/examples/ is illustrative unless a governing standard explicitly says otherwise.

Accepted repository-specific ADRs and explicit local policy may refine or supersede imported standards. Do not silently deviate from an applicable standard. Do not edit imported standards locally; project-specific exceptions belong in repository governance. .codingstandardrc records the concrete upstream release and archive digest for the managed snapshot.

Documentation Standards

Maintained JavaScript documentation follows doc/standards/javascript/documentation-standard.md, whose canonical upstream is wesley-dean/coding_standards/standards/javascript/documentation-standard.md. JSDoc is therefore the maintained source documentation language for JavaScript in this repository.

The shared standard defines valid maintained-source forms. Filter and consumer- configuration support are separate, narrower contracts governed by this repository's accepted ADRs and regression tests. Do not infer that doxygen-javascript.awk translates or that Doxygen natively or through aliases supports a JSDoc construct merely because the shared standard permits that construct.

Maintained AWK source follows doc/standards/awk/documentation-standard.md, whose canonical upstream is wesley-dean/coding_standards/standards/awk/documentation-standard.md.

Architecture and Scope

ADR-012 establishes the JavaScript filter and TAP regression boundary. ADR-013 adds canonical required-parameter translation. ADR-014 adds canonical optional parameters with and without compact documented defaults. ADR-016 adds canonical typed @returns translation while preserving the @returns command itself. ADR-017 adds canonical typed-and-described @throws translation by removing the JSDoc type braces and preserving Doxygen's native exception-object position. ADR-018 establishes downstream JavaScript/Doxygen integration evidence for those already-governed forms. ADR-019 adds canonical typed @yields translation through a line-preserving generated @jsyields command plus a required Doxygen alias. ADR-020 establishes that canonical JSDoc records that are already semantically and syntactically compatible with Doxygen should pass through unchanged when focused TAP and integration evidence prove that compatibility. ADR-021 represents canonical virtual JSDoc typedefs as Doxygen related pages so they remain named and cross-referenceable without fabricating JavaScript declarations. ADR-022 adds canonical simple properties as structured child documentation on those pages. ADR-023 represents named simple callbacks as a distinct virtual-page entity and reuses already-governed parameter and return translations for callback signatures. ADR-024 supports canonical @type {Type} annotations by leaving the maintained JSDoc record unchanged and defining its Doxygen presentation entirely in consumer configuration. ADR-025 establishes the JavaScript-specific generated artifact, checksum, build-dependency, and source/dist parity contract. ADR-026 publishes those generated artifacts as semantic-versioned GitHub release assets and adds a post-publication exact-public-bytes canary. ADR-027 supersedes only the artifact and consumer filename portions of ADR-025 and ADR-026, standardizing them on the Doxygen-first sibling convention and removing the copied root Python filter.

Supported parameter, virtual typedef, governed typedef-property, and callback names remain simple JavaScript identifiers. The filter keeps type expressions and supported optional defaults as textual documentation data rather than interpreting them as JavaScript semantics. Compact defaults must be non-empty and contain neither whitespace nor ] in the current grammar.

Canonical typed returns use @returns {Type} Description. and are emitted as @returns Description. Type: Type.. Canonical typed exceptions use @throws {Type} Description. with a compact non-whitespace exception type and are emitted as @throws Type Description.. Canonical typed yields use @yields {Type} Description. and are emitted as @jsyields Type: Type. Description..

@jsyields is generated Doxygen-facing syntax only. Maintainers SHALL continue to write JSDoc @yields. A consuming repository SHALL define the governed alias in its own Doxyfile:

ALIASES += jsyields="@par Yields^^"

The alias introduces the logical newline required for a Doxygen Yields paragraph without changing the filter's physical line count. The checked-in doxygen-javascript.conf file is the repository's canonical integration-test and reference copy of the alias configuration; it is not a downstream runtime dependency.

Canonical @deprecated Description. and @see Reference records are currently accepted as native-compatible forms under ADR-020. The filter SHALL preserve them unchanged. Do not normalize @see to @sa, wrap native-compatible tags in aliases, or claim another same-named JSDoc/Doxygen tag is supported without focused pass-through and downstream semantic evidence.

Canonical virtual typedefs use @typedef {Type} Name. ADR-021 requires the filter to emit a generated @jstypedef alias invocation on the same physical line. The consumer-owned Doxyfile alias expands to a Doxygen related page whose visible title is the exact JSDoc typedef name. The page is a documentation entity, not a runtime JavaScript class, struct, interface, function, variable, or native typedef declaration. Do not synthesize fake JavaScript declarations to create documentation symbols.

Virtual typedef page labels are deterministic generated identifiers. Maintained source authors SHALL NOT write or duplicate those labels. Generated labels use a lowercase alphanumeric encoding so JavaScript case-sensitive identifiers remain distinct without relying on Doxygen page-name case behavior. Consumers may use the generated labels as Doxygen @ref targets where the generated representation needs cross-references.

Canonical typedef properties use @property {Type} name - Description. and are supported only after a governed virtual typedef has already been established in the same JSDoc block. ADR-022 requires the filter to emit a generated @jsproperty alias invocation on the same physical line. The alias renders a Property: name paragraph on the existing virtual typedef page. The property SHALL NOT become a fake JavaScript member, field, variable, accessor, or standalone page. A property outside a governed virtual typedef block remains unchanged.

Canonical callbacks use @callback Name with a simple JavaScript identifier. ADR-023 requires the filter to emit a line-preserving generated @jscallback record whose alias creates a related page titled with the exact callback name. Callback labels use a distinct jsdocvirtualcallback namespace so a callback and a typedef with the same maintained name cannot collide. The callback page is a virtual documentation entity; the filter SHALL NOT synthesize a JavaScript or Doxygen function declaration.

Already-governed canonical @param and typed @returns records in the same callback block retain their existing translations. Integration evidence SHALL prove that Doxygen renders those sections inside the callback page. Do not add a second callback-specific parameter or return representation while the existing representation remains sufficient.

Canonical symbol type annotations use:

@type {Type}

ADR-024 requires doxygen-javascript.awk to preserve this maintained JSDoc record unchanged. A consuming repository that uses this governed rendering SHALL define the alias in its own Doxyfile:

ALIASES += type="@par Type^^"

The alias renders the maintained expression as a Type paragraph attached to the symbol documented by the surrounding block. The braces and expression remain textual documentation data. Do not parse, normalize, infer, validate, or claim native Doxygen type semantics from this representation. The alias is presentation, not type-system integration.

The singular JSDoc synonym @return, untyped returns, typed returns without descriptions, description-only @throws, type-only @throws, throws types with whitespace, description-only @yields, type-only @yields, unsupported typedef forms, continuation records, dotted properties, optional dotted properties, rest parameters, destructured parameter documentation, standalone properties, complex callback namepaths such as Requester~requestCallback, automatic linking of type expressions to virtual typedef or callback pages, and one-line JSDoc blocks remain unsupported unless a later accepted decision governs them.

Future JSDoc support should remain narrow and evidence-driven. Prefer visible unsupported syntax to speculative semantic claims. Do not add JavaScript parsing, type inference, inferred behavior, broad JSDoc semantics, blanket native-tag support, blanket consumer-alias support, or synthetic runtime declarations without explicit governance and focused tests.

All governed filter transformations preserve one physical output record for every input record. test/run-tests.sh verifies physical line-count equality for every fixture. ADR-024 @type support is stronger still at the filter boundary: the maintained record is byte-preserved. Doxygen's input-filter contract associates filtered text with source locations and source-browser anchors, so proposals that add or remove physical lines require explicit governance plus integration evidence rather than being treated as harmless formatting changes.

Historical copied Python tests, ADRs, and workflow references may remain during migration as reference material. They are not current JavaScript capability claims where ADR-012 and later JavaScript-specific decisions supersede their Python-specific contracts. ADR-027 removes the copied root doxygen-python.awk implementation; the independent python-doxygen repository is the maintained source for that filter.

Consumer Integration

Downstream consumption follows the sibling filter model. A consuming repository uses bashdeps to pin one released JavaScript filter and materializes that one runtime dependency conventionally as:

vendor/doxygen-javascript.awk

The consumer owns its Doxyfile. It SHALL map JavaScript files to Doxygen's JavaScript parser, apply the vendored filter through FILTER_PATTERNS, and include the governed alias definitions needed by the supported alias-backed representations. The README is the human-facing setup reference for the exact current Doxyfile block.

Do not turn doxygen-javascript.conf into a second Bashdeps dependency. It exists to keep repository integration tests and the reference alias contract inspectable. The downstream runtime dependency model remains exactly one AWK filter file.

Build and Distribution

ADR-025 establishes the local generated-artifact lifecycle; ADR-027 normalizes its filenames. The current build outputs are:

dist/doxygen-javascript.dev.awk
dist/doxygen-javascript.dev.awk.sha256
dist/doxygen-javascript.awk
dist/doxygen-javascript.awk.sha256
dist/doxygen-javascript.min.awk
dist/doxygen-javascript.min.awk.sha256

The development artifact retains all maintained AWK documentation. The ordinary artifact removes only project-governed ## Doxygen documentation records. The minified artifact is derived from the ordinary artifact body by the pinned released AWK Minifier synchronized through bashdeps; generated provenance is kept outside the minifier input.

Build dependency acquisition and build execution are separate boundaries:

make deps
make deps-check
make build

make deps may use the network. make deps-check and make build are offline and non-repairing. make all is the convenience lifecycle that runs dependency preparation and then builds all six outputs. Do not add hidden downloads to make build, silently fall back to another minifier, or use the current candidate as its own production minifier.

dependencies.txt owns build dependencies. dependencies-docs.txt owns self-documentation dependencies. Both may materialize files under vendor/; Bashdeps synchronization does not prune files omitted from the current manifest.

Generated dist/ content is untracked. Every generated AWK artifact must preserve the maintained filter's tested semantics and must have a valid adjacent SHA-256 file in ordinary sha256sum-compatible format.

Release Publication

ADR-026 governs the semantic-version release interface, with current filenames normalized by ADR-027. The versioning workflow runs on pushes to main and may be invoked manually. It SHALL calculate the prospective version without creating a tag, validate maintained source, run make all VERSION=<version> AWK_BIN=mawk, and exercise the exact generated artifacts under both mawk and GNU awk plus Doxygen before creating a release.

The release SHALL publish exactly the three current AWK artifacts and their three adjacent SHA-256 files. The ordinary doxygen-javascript.awk file is the canonical normal Bashdeps consumer artifact. Development and minified files are alternate published representations and do not add runtime dependencies.

Release v0.0.3 remains historically valid with its original javascript-doxygen*.awk filenames. Beginning with the first ADR-027 release, the release interface uses only the normalized doxygen-javascript*.awk names. Historical release assets SHALL NOT be renamed or replaced merely to match the current convention.

The release tag SHALL be created only after validation succeeds and SHALL identify the exact validated commit. Workflow YAML SHALL NOT duplicate Make-owned build, minification, checksum, TAP, or Doxygen logic.

A dependent post-publication canary SHALL download all six public release assets, verify the three hashes, and run TAP plus Doxygen integration against every downloaded AWK artifact under both supported AWK implementations. The canary is verification only: it SHALL NOT advance stable dependency pins or mutate unrelated repository state.

doxygen-javascript.conf remains repository reference/integration data and SHALL NOT become a release runtime asset. Normal consumers pin a specific semantic version of doxygen-javascript.awk, its public release URL, and its expected digest through Bashdeps. Consumers remaining on v0.0.3 use that release's historical javascript-doxygen.awk name.

Portability and Testing

Portable AWK is the compatibility floor. Production filter source and generated artifacts must run under at least mawk and GNU awk.

Behavior-focused JavaScript fixtures live under test/fixtures/. Golden filtered output lives under test/expected/. test/run-tests.sh emits TAP version 13 and verifies line-count preservation for every fixture.

Use:

make test AWK_BIN=mawk
make test AWK_BIN=gawk

The current TAP suite proves ordinary source pass-through; required-parameter translation; optional-parameter translation with and without compact documented defaults; visible pass-through of unsupported dotted property notation; canonical typed @returns translation; visible pass-through of singular @return; canonical typed-and-described @throws translation; visible pass-through of description-only and type-only throws forms; canonical typed @yields translation; visible pass-through of description-only and type-only yields forms; unchanged pass-through of accepted native-compatible @deprecated and @see records; canonical virtual typedef translation; visible pass-through of unsupported typedef forms; canonical property translation under a governed typedef; visible pass-through of a standalone property; canonical named callback translation; visible pass-through of an unsupported callback namepath; and byte-preserved canonical @type annotation pass-through. Add a focused fixture and expected output when adding each new supported translation, native-compatible behavior, or consumer-alias behavior. Tests should protect externally observable behavior rather than internal helper structure.

ADR-018 adds a separate downstream integration surface beneath test/doxygen/. ADR-019 extends that surface with the alias-backed yields representation. ADR-020 uses the same surface to prove native-compatible semantics. ADR-021 adds named related-page and cross-reference evidence for virtual typedefs. ADR-022 adds property-on-page evidence. ADR-023 adds named callback-page evidence with parameter, return, and cross-reference assertions. ADR-024 adds symbol-local Type paragraph evidence for unchanged canonical JSDoc @type records. Use:

make test-doxygen AWK_BIN=mawk
make test-doxygen AWK_BIN=gawk

The repository integration configuration parses .js input as JavaScript, applies the selected filter through Doxygen's input-filter mechanism, loads the repository-only doxygen-javascript.conf reference fragment, generates XML, and checks semantic structure for governed parameter, return, exception, yield, deprecation, see-also, virtual typedef, typedef-property, callback, and type- annotation forms. The yields integration assertions SHALL verify both a dedicated Yields paragraph and source-location evidence for the generator fixture. Native- compatible tag assertions SHALL prove that unchanged source records are interpreted by Doxygen as the intended semantic structures. Virtual typedef assertions SHALL prove that Doxygen creates a named related page, retains the maintained prose and base type, and resolves a reference to the generated page label. Property assertions SHALL prove that the property heading, type, and description occur inside the generated virtual typedef page. Callback assertions SHALL prove named page creation, parameter and return sections inside that page, and resolved references to the generated callback label. Type-annotation assertions SHALL prove that the maintained @type record remains unchanged through the filter and that Doxygen attaches the configured Type paragraph and retained expression to the documented symbol. CI SHALL exercise this path under both portable-AWK implementations. Keep this surface separate from make test so textual filter failures and downstream Doxygen failures remain independently diagnosable.

ADR-025 adds generated-artifact parity surfaces. Use:

make test-dist AWK_BIN=mawk
make test-dist AWK_BIN=gawk
make test-dist-doxygen AWK_BIN=mawk
make test-dist-doxygen AWK_BIN=gawk

test-dist validates artifact shape, all adjacent checksums, and the full TAP suite against development, ordinary, and minified artifacts. test-dist-doxygen exercises each generated artifact through the same Doxygen integration contract. CI runs both artifact surfaces under mawk and GNU awk after make all.

ADR-026 extends the same evidence to release publication. Pre-publication gates exercise the exact generated release candidates; the post-publication canary then repeats TAP and Doxygen integration against the exact public release bytes.

Project Self-Documentation

ADR-015 restores project self-documentation independently of JavaScript/Doxygen integration. doxygen-javascript.awk is AWK source and is documented with the pinned released awk-doxygen filter. test/run-tests.sh is Bash source and is documented with the pinned released bash-doxygen filter.

Use:

make deps-docs
make deps-docs-check
make docs AWK_BIN=mawk

The documentation canary SHALL exercise this path on pull requests. Pages SHALL publish the generated doc/reference/ tree after pushes to main. Generated vendor/, doc/reference/, and doc/adr/README.md state remains untracked.

Project self-documentation and JavaScript/Doxygen integration are separate capabilities with separate evidence. Passing one does not substitute for the other.

Deferred Infrastructure

Do not reactivate copied Python-specific release paths or add no-op compatibility targets. Future release changes SHALL preserve ADR-025, ADR-026, and ADR-027 unless a new or superseding accepted decision explicitly changes the public contract.

Engineering Approach

Keep changes surgical and reviewable. Accuracy is more important than apparent completeness. Distinguish implemented behavior from planned behavior, state uncertainty explicitly, and do not widen the parser, generated representation, native-compatible or consumer-alias support boundary, virtual-type entity model, consumer configuration, build/distribution contract, or release boundary without governance and focused executable evidence.