Skip to content

chore: remove orphaned @event JSDoc blocks (post-CEM cleanup)#11621

Merged
web-padawan merged 1 commit intomainfrom
chore/remove-event-jsdoc-blocks
Apr 30, 2026
Merged

chore: remove orphaned @event JSDoc blocks (post-CEM cleanup)#11621
web-padawan merged 1 commit intomainfrom
chore/remove-event-jsdoc-blocks

Conversation

@web-padawan
Copy link
Copy Markdown
Member

@web-padawan web-padawan commented Apr 30, 2026

Summary

Now that #11539 has migrated web-types and API docs generation to CEM, event documentation is canonically expressed via @fires {CustomEvent} <name> - … lines on the class JSDoc. CEM does not read @event JSDoc blocks at all.

The 2026-04-29 batch (#11604#11610) plus follow-up #11619 copied long descriptions from @event blocks into the corresponding @fires lines. The @event blocks remained in source as duplicate dead documentation.

This PR removes them: 129 blocks across 49 .js files, ~928 lines deleted. Concentrated in:

  • charts (34 blocks in vaadin-chart-mixin.js)
  • upload (13 blocks)
  • grid (12 blocks)
  • dashboard (7 blocks)
  • overlay, crud, combo-box, dialog, date-picker, confirm-dialog, plus 22 other packages with 1–3 blocks each

.d.ts files are untouched.

Verification — web-types output is byte-identical

Per the user's stated success criterion. Snapshotted custom-elements.json and all 120 per-package web-types.json / web-types.lit.json files before the cleanup, applied the change, regenerated everything, and confirmed via diff -r that every per-package output is byte-identical.

# Before changes:
yarn release:cem && yarn release:web-types
mkdir -p /tmp/cem-before
for f in packages/*/web-types.json packages/*/web-types.lit.json; do
  mkdir -p /tmp/cem-before/$(dirname "$f"); cp "$f" /tmp/cem-before/"$f"
done

# Apply this PR's diff, then:
yarn release:cem && yarn release:web-types
diff -r /tmp/cem-before/packages packages/   # empty ✓

The root custom-elements.json shows module-ordering variation between runs (a pre-existing CEM-analyzer non-determinism), but every module's content is identical when sorted by path. Per-package CEM output that's published to npm is unaffected.

Note on @param detail.* documentation

A handful of @event blocks (in vaadin-upload.js, vaadin-chart-mixin.js, vaadin-crud-mixin.js) included @param detail.* lines describing the detail object's shape. The shape itself remains fully captured by the CustomEvent<{…}> type parameter on the *Event type aliases in .d.ts files (e.g., UploadBeforeEvent = CustomEvent<{ xhr: XMLHttpRequest; file: UploadFile }>), which IDE / TS users consume directly. The @param detail.* lines were never read by Polymer Analyzer or CEM — they were inline source-only prose.

If a specific @param detail.x description is judged worth preserving, it can be lifted into the affected component's @fires line in a follow-up.

Test plan

  • yarn release:cem and yarn release:web-types produce byte-identical per-package output vs. the pre-change snapshot
  • yarn lint and yarn lint:types pass
  • git diff --stat -- 'packages/*/src/*.d.ts' is empty (.d.ts files untouched)
  • Spot-check that @fires lines are still present and unchanged on the affected components
  • CI tests pass

🤖 Generated with Claude Code

Now that #11539 has migrated web-types and API docs generation to CEM,
event documentation is canonically expressed via `@fires {CustomEvent}
<name> - …` lines on the class JSDoc. CEM does not read `@event` JSDoc
blocks at all.

The 2026-04-29 batch (#11604#11610 + follow-up #11619) copied long
descriptions from `@event` blocks into the corresponding `@fires`
lines. The `@event` blocks remained in source as duplicate dead
documentation, kept only because nobody got around to deleting them.

Remove them now: 129 blocks across 49 `.js` files. Web-types output
(per-package `web-types.json` and `web-types.lit.json`) is byte-identical
before and after the removal — verified by snapshotting both files for
all 60 packages, running `yarn release:cem && yarn release:web-types`,
and `diff -r`-ing against the snapshot. Empty diff confirms CEM ignores
`@event` as expected.

The CustomEvent `detail` shape, which some `@event` blocks documented
via `@param detail.*` lines, is captured by the `*Event` type aliases
in `.d.ts` files (e.g., `UploadBeforeEvent = CustomEvent<{ xhr: XMLHttpRequest;
file: UploadFile }>`). `.d.ts` files are untouched in this commit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@sonarqubecloud
Copy link
Copy Markdown

@web-padawan web-padawan removed the request for review from sissbruecker April 30, 2026 09:57
@web-padawan web-padawan merged commit 5989ade into main Apr 30, 2026
10 checks passed
@web-padawan web-padawan deleted the chore/remove-event-jsdoc-blocks branch April 30, 2026 09:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants