2065656 - Fix the truncated TabMetricsContext typedef in TabMetrics.sys.mjs

Status: RESOLVED FIXED

(Firefox :: Tabbed Browser, task)

Description

[Dão Gottwald [:dao]]

Filing as a good first bug to learn workflows.

The TabMetricsContext typedef in TabMetrics.sys.mjs documents three properties, but TypeScript only sees the first two. An indented @see sits inside the telemetrySource property description:

 * @property {string} [telemetrySource="unknown"]
 *   The system, surface, or control the user used to take this action.
 *   @see TabMetrics.METRIC_SOURCE for possible values.
 *   Defaults to "unknown".
 * @property {boolean} [isDecomposed=false]

TypeScript's JSDoc parser reads @see as the start of a new block tag and stops collecting @property tags there, so isDecomposed is not part of the type. Note that jsdoc itself is unaffected -- it reports all three properties -- so this is a TypeScript-compatibility fix, not a rendering bug.

The fix is to keep the reference but not as a tag, for example by folding it into the prose:

 * @property {string} [telemetrySource="unknown"]
 *   The system, surface, or control the user used to take this action, one of
 *   the TabMetrics.METRIC_SOURCE values. Defaults to "unknown".

Link to the code:
https://searchfox.org/firefox-main/source/browser/components/tabbrowser/TabMetrics.sys.mjs#84

To verify the fix:

browser/components/tabbrowser is not type-checked in CI yet, so use a scratch project. From the top of your checkout:

mkdir -p artifacts/tm-probe
cat > artifacts/tm-probe/tsconfig.json <<EOF
{
"include": ["../../browser/components/tabbrowser/TabMetrics.sys.mjs"],
"extends": "../../tools/@types/tsconfig.json",
"compilerOptions": {
"checkJs": true, "strict": true, "noImplicitAny": false, "strictNullChecks": false,
"plugins": [{ "transform": "../../tools/ts/plugins/checkRootOnly.js", "transformProgram": true }]
}
}
EOF
./mach node node_modules/typescript/bin/tsc --project artifacts/tm-probe --pretty false

Before the fix that prints:

browser/components/tabbrowser/TabMetrics.sys.mjs(129,5): error TS2353: Object literal may only specify known properties, and 'isDecomposed' does not exist in type 'TabMetricsContext'.

After the fix it prints nothing. (If the command fails because node_modules is missing, run ./mach lint -l eslint browser/components/tabbrowser/TabMetrics.sys.mjs once to populate it.)

Please also run:

./mach lint -l eslint browser/components/tabbrowser/TabMetrics.sys.mjs

Tutorial to contribute:
https://firefox-source-docs.mozilla.org/contributing/contribution_quickref.html
https://firefox-source-docs.mozilla.org/contributing/stack_quickref.html

Please don't ask for the bug to be assigned. It will be automatically assigned to the first patch.

Comment 1

[Dão Gottwald [:dao]]

Attachment: Bug 2065656 - Make the whole TabMetricsContext typedef visible to TypeScript. r?jsudiaman!

TypeScript's JSDoc parser reads the indented @see as the start of a new block tag and stops collecting @property tags there, so isDecomposed was not part of the type. jsdoc itself is unaffected either way, so the rendered documentation does not change.

Comment 2

[Pulsebot]

Pushed by [e-mail]:
https://github.com/mozilla-firefox/firefox/commit/c70785929336
https://hg.mozilla.org/integration/autoland/rev/d889f28d73af
Make the whole TabMetricsContext typedef visible to TypeScript. r=jsudiaman,tabbrowser-reviewers

Comment 3

[Sandor Molnar[:smolnar]]

https://hg.mozilla.org/mozilla-central/rev/d889f28d73af