Skip to content

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

Open
fibibot wants to merge 2 commits into
denoland:mainfrom
fibibot:fix/module-doc-not-attached-to-first-symbol
Open

fix: don't attach @module JSDoc to the first symbol#795
fibibot wants to merge 2 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

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.

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