Make sure everything is documented from Typedoc's point of view by amezin · Pull Request #32 · ddterm/gjs-test

amezin · 2026-11-08T02:45:49Z

No description provided.

coderabbitai · 2026-11-08T02:45:58Z

No actionable comments were generated in the recent review.

Summary

Summary by CodeRabbit

Documentation
- Improved API documentation for assertion errors and callback types.
- Enabled checks for undocumented public entities and stricter documentation validation.
Chores
- Updated the documentation workflow to fail when TypeDoc reports warnings.

This change adds JSDoc lint rules, updates documentation comments, enables TypeDoc checks for undocumented items, and configures CI to treat TypeDoc warnings as errors.

Changes: Documentation validation

Layer / File(s)	Summary
JSDoc rules and comments `eslint.config.mjs`, `assert.js`, `reporter.js`, `tests/snapshots/tap-report.txt`	ESLint adds JSDoc checks for properties, callbacks, and typedefs. Related comments are updated, and the assertion snapshot reflects changed line numbers.
TypeDoc validation in CI `typedoc.jsonc`, `.github/workflows/ci.yml`	TypeDoc checks for undocumented items. The CI documentation job runs TypeDoc with warnings treated as errors.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Other

Possibly related PRs

ddterm/gjs-test#19: Adds AssertionError documentation and the TAP snapshot whose stack locations are updated here.

Merge Risk: Minimal · up to 20c2a

Documentation validation becomes stricter without an identified merge-blocking issue.

Pre-merge checks: 3 · 1

Failed checks: 1 inconclusive

Check name	Status	Explanation	Resolution
Description check		The author provided no description. The check is lenient, and the PR objectives describe the same goal as the changeset. The description check therefore does not fail. The check is inconclusive becaus…	Add a pull request description that summarizes the changes. Include the TypeDoc validation option, the CI doc job change, the ESLint JSDoc rules, and the documentation fixes in assert.js and reporter.js.

Passed checks: 3 passed

Check name	Status	Explanation
Title check		The title states that everything is documented from TypeDoc's point of view. The changeset matches this goal: typedoc.jsonc enables validation.notDocumented, the CI doc job runs TypeDoc with --treatWa…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Title check

Explanation

The title states that everything is documented from TypeDoc's point of view. The changeset matches this goal: typedoc.jsonc enables validation.notDocumented, the CI doc job runs TypeDoc with --treatWarningsAsErrors, ESLint JSDoc rules were added, and JSDoc comments in assert.js and reporter.js were corrected or expanded. The title is specific and clearly describes the primary change.

Full details: Description check

Explanation

The author provided no description. The check is lenient, and the PR objectives describe the same goal as the changeset. The description check therefore does not fail. The check is inconclusive because the author added no description text that describes the changes.

Resolution

Add a pull request description that summarizes the changes. Include the TypeDoc validation option, the CI doc job change, the ESLint JSDoc rules, and the documentation fixes in assert.js and reporter.js.

Finishing Touches

Generate docstrings

Commit to this branch
Create a new PR

Generate unit tests (beta)

Commit to this branch
Create a new PR

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Some tools did not complete. Review the errors below.

ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

assert.js

Parsing error: Could not read Project Service default project './tsconfig.node.json': Unable to parse the specified 'tsconfig' file. Ensure it's correct and has valid syntax.

./tsconfig.node.json(7,5): error TS6053: File '@tsconfig/bases/strictest' not found.
./tsconfig.node.json(8,5): error TS6053: File '@tsconfig/bases/node22' not found.

eslint.config.mjs

Parsing error: Could not read Project Service default project './tsconfig.node.json': Unable to parse the specified 'tsconfig' file. Ensure it's correct and has valid syntax.

./tsconfig.node.json(7,5): error TS6053: File '@tsconfig/bases/strictest' not found.
./tsconfig.node.json(8,5): error TS6053: File '@tsconfig/bases/node22' not found.

reporter.js

Parsing error: Could not read Project Service default project './tsconfig.node.json': Unable to parse the specified 'tsconfig' file. Ensure it's correct and has valid syntax.

./tsconfig.node.json(7,5): error TS6053: File '@tsconfig/bases/strictest' not found.
./tsconfig.node.json(8,5): error TS6053: File '@tsconfig/bases/node22' not found.

Tip

🎯 Customize your risk assessments

Guide how CodeRabbit assesses merge risk and security architecture risk. Highlight sensitive changes and explain your security boundaries using Merge Risk Instructions and Security Risk Instructions in your review settings. Security architecture risk assessments require the Advanced plan or above.

✅ Automatic approvals, with your rules

Let CodeRabbit approve pull requests once required threads are resolved, pre-merge checks pass, and your risk limits are met. Enable Automatic approvals in review settings, with overrides for teams or file paths.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Recent review info

Run configuration

Source mode: Auto

Repository: Unavailable

Branch: Unavailable

File: No configuration file from this repository applied

Commit: Unavailable

Layers: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: `5069b4e7-ba09-4670-a3d7-feeb5161a688`

Commits

Reviewing files that changed from the base of the PR and between `edefe78` and `20c2a3c`.

Files selected for processing: 6

`.github/workflows/ci.yml`

`assert.js`

`eslint.config.mjs`

`reporter.js`

`tests/snapshots/tap-report.txt`

`typedoc.jsonc`

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Recent review details

Additional comments: 6

eslint.config.mjs: 1

`68-72`: LGTM!

Also applies to: 115-117, 133-133, 146-159

assert.js: 1

`11-11`: LGTM!

Also applies to: 19-19, 33-34, 50-53, 55-55, 57-60, 62-62

reporter.js: 1

`52-52`: LGTM!

tests/snapshots/tap-report.txt: 1

`10-10`: LGTM!

Also applies to: 17-17

typedoc.jsonc: 1

`15-16`: LGTM!

.github/workflows/ci.yml: 1

`101-101`: LGTM!

codecov · 2026-11-08T02:48:08Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.97%. Comparing base (edefe78) to head (20c2a3c).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #32   +/-   ##
=======================================
  Coverage   82.97%   82.97%           
=======================================
  Files           3        3           
  Lines         282      282           
=======================================
  Hits          234      234           
  Misses         48       48

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

qodo-free-for-open-source-projects · 2026-11-08T05:29:45Z

PR Summary by Qodo

Enforce TypeDoc documentation coverage in CI

📝 Documentation ⚙️ Configuration changes 🕐 10-20 Minutes

AI Description

• Fail documentation builds when TypeDoc finds undocumented API elements or other warnings.
• Require JSDoc descriptions that TypeDoc recognizes for callbacks, typedefs, and properties.
• Document assertion properties and refresh the affected test snapshot.

Diagram

graph TD
    CI["CI documentation job"] --> TypeDoc["TypeDoc build"] --> HTML["HTML documentation"]
    CI --> ESLint["ESLint checks"] --> Sources["JSDoc sources"] --> TypeDoc
    Config["TypeDoc validation"] --> TypeDoc

High-Level Assessment

The following are alternative approaches to this PR:

1. Use TypeDoc validation alone

➕ Fewer custom ESLint rules to maintain.
➖ Loses targeted lint feedback for JSDoc layouts that TypeDoc ignores.

Recommendation: Keep the combined approach: TypeDoc checks the generated API documentation, while ESLint catches incompatible comment patterns closer to their source.

Files changed (6) +44 / -8

Tests (1) +2 / -2

tap-report.txtRefresh assertion stack locations in TAP snapshot +2/-2

Refresh assertion stack locations in TAP snapshot
• Updates source line numbers in the captured assertion error and stack trace after the added comments.
tests/snapshots/tap-report.txt

Documentation (2) +15 / -5

assert.jsMake assertion API comments visible to TypeDoc +14/-4

Make assertion API comments visible to TypeDoc

• Moves callback and typedef descriptions after their tags. Documents the error name and conditionally assigned expected and actual properties.

assert.js

reporter.jsExpose the Print callback description to TypeDoc +1/-1

Expose the Print callback description to TypeDoc
• Moves the Print callback description after its JSDoc tag so TypeDoc recognizes it.
reporter.js

Other (3) +27 / -1

ci.ymlFail the documentation job on TypeDoc warnings +1/-1

Fail the documentation job on TypeDoc warnings
• Runs TypeDoc directly with warnings treated as errors before uploading the generated documentation.
.github/workflows/ci.yml

eslint.config.mjsEnforce TypeDoc-compatible JSDoc conventions +23/-0

Enforce TypeDoc-compatible JSDoc conventions

• Requires documentation and descriptions for identifier-named properties. Adds rules against callback and typedef descriptions that TypeDoc ignores or finds missing, and preserves documentation alongside override tags.

eslint.config.mjs

typedoc.jsoncEnable undocumented-API validation +3/-0

Enable undocumented-API validation

• Enables TypeDoc's notDocumented validation so missing API documentation produces warnings that CI treats as errors.

typedoc.jsonc

qodo-free-for-open-source-projects · 2026-11-08T05:29:52Z

Code Review by Qodo

🐞 Bugs (1) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. CI now bypasses the doc script it used to run 🐞 Bug ⚙ Maintainability

Description

The workflow step changed from npm run doc to npm run doc:typedoc -- --treatWarningsAsErrors, so
CI no longer runs the doc aggregate script (run-s doc:*) and instead hardcodes one sub-script
with a flag that the local doc script does not use. Any future doc:* script added to
package.json will be silently skipped in CI, and local npm run doc can pass while CI fails on
warnings.

Code

.github/workflows/ci.yml[101]
+      - run: npm run doc:typedoc -- --treatWarningsAsErrors

Evidence

package.json defines doc as run-s doc:* and doc:typedoc as typedoc. The workflow now calls
doc:typedoc directly with --treatWarningsAsErrors, which is enforced only in CI and not in the
doc script developers run locally.

package.json[47-48]
.github/workflows/ci.yml[101-101]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
CI invokes `doc:typedoc` directly with `--treatWarningsAsErrors`, bypassing the `doc` aggregate script and diverging from what developers run locally.
## Fix Focus Areas
- .github/workflows/ci.yml[101-101]
- package.json[47-48]
## Recommended Fix
Either keep `- run: npm run doc` in CI and move `--treatWarningsAsErrors` into the `doc:typedoc` script (e.g. `"doc:typedoc": "typedoc --treatWarningsAsErrors"`), or make the flag part of the `doc` script so local and CI runs match and any future `doc:*` script still runs in CI.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Tip of the day

💡 Did you know, you can pick a display mode instead of tweaking every Display option by hand

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Make sure everything is documented from Typedoc's point of view

20c2a3c

amezin force-pushed the typedoc-not-documented branch from f37884d to 20c2a3c Compare November 8, 2026 05:05

amezin marked this pull request as ready for review November 8, 2026 05:27

amezin merged commit 20c2a3c into main Nov 8, 2026
12 checks passed

amezin deployed to github-pages November 8, 2026 06:15 — with GitHub Actions

View deployment

Navigation Menu

Repository navigation

Make sure everything is documented from Typedoc's point of view - #32

Make sure everything is documented from Typedoc's point of view#32
amezin merged 1 commit into
mainfrom
typedoc-not-documented

amezin commented Nov 8, 2026

Uh oh!

coderabbitai Bot commented Nov 8, 2026 •

edited

Loading

Summary by CodeRabbit

Uh oh!

codecov Bot commented Nov 8, 2026 •

edited

Loading

Uh oh!

qodo-free-for-open-source-projects Bot commented Nov 8, 2026

Uh oh!

qodo-free-for-open-source-projects Bot commented Nov 8, 2026 •

edited

Loading

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

amezin commented Nov 8, 2026

Uh oh!

coderabbitai Bot commented Nov 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

codecov Bot commented Nov 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

qodo-free-for-open-source-projects Bot commented Nov 8, 2026

PR Summary by Qodo

Uh oh!

qodo-free-for-open-source-projects Bot commented Nov 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Review by Qodo

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

coderabbitai Bot commented Nov 8, 2026 •

edited

Loading

codecov Bot commented Nov 8, 2026 •

edited

Loading

qodo-free-for-open-source-projects Bot commented Nov 8, 2026 •

edited

Loading