Skip to content

fix: don't attach @module JSDoc to the first symbol - #795

Merged
crowlKats merged 3 commits into
denoland:mainfrom
fibibot:fix/module-doc-not-attached-to-first-symbol
Oct 25, 2026
Merged

crowlKats merged 3 commits into
denoland:mainfrom
fibibot:fix/module-doc-not-attached-to-first-symbol

Conversation

@fibibot

@fibibot fibibot commented Apr 26, 2026

Copy link
Copy Markdown
Contributor

Summary

Reported as denoland/deno#30783. `js_doc_for_range_include_ignore` walks leading comments back from a symbol's range to find its JSDoc block. When a file's `@module` documentation comment was the only leading block before an undocumented exported symbol, that comment was returned as the symbol's JSDoc — so the same paragraph appeared twice in `deno doc` output and on an unrelated symbol:

```js
/**

export function foo() {}

/** This is the bar function. */
export function bar() {}
```

```
$ deno doc bug.js
The module docs.
@module

Defined in file:///bug.js:9:1

function bar(): void
This is the bar function.

Defined in file:///bug.js:6:1

function foo(): void
The module docs. <-- duplicated module-level doc
@module
```

Skip JSDoc blocks tagged `@module` when resolving per-symbol docs. They're file-level by intent and have already been collected by `module_js_doc_for_source`.

Test plan

  • New `tests/specs/module_docs_undocumented_first_symbol.txt` spec captures the regression — the regenerated output (via `UPDATE=1`) shows `foo` with no `jsDoc` field and `module_doc` containing the `@module` block.
  • Existing `module_docs`, `module_docs_ignore`, `module_docs_ignore_no_module_tag` specs still pass.
  • `cargo fmt --check`, `cargo clippy --tests -- -D warnings`.

`js_doc_for_range_include_ignore` walks leading comments back from a
symbol's range to find its JSDoc block. When a file's `@module`
documentation comment was the only leading block before an undocumented
exported symbol, that comment was returned as the symbol's JSDoc — so
the same paragraph showed up twice in `deno doc` output and on
unrelated symbols.

Skip JSDoc blocks tagged `@module` when resolving per-symbol docs.
Such blocks are file-level by intent and have already been collected
by `module_js_doc_for_source`.

Fixes denoland/deno#30783.
@CLAassistant

CLAassistant commented Apr 26, 2026 •

Copy link
Copy Markdown

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ crowlKats
❌ fibibot
You have signed the CLA already but the status is still pending? Let us recheck it.

@crowlKats
crowlKats merged commit 6711699 into denoland:main Oct 25, 2026
4 of 5 checks passed
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.

3 participants