docs(guardrails): enforce JSDoc on every new or modified function

[PierreBrisorgueil]

Summary

• Add JSDoc rule to copilot-instructions.md guardrails: every new or modified function must have a JSDoc header (description + @param + @returns)
• Add entry to ERRORS.md to reinforce the lesson from PRs where functions were added without documentation

Why

Recent PRs introduced functions without JSDoc headers. This rule makes it an always-on constraint for all AI interactions rather than a post-hoc catch.

Scope

• Tooling/docs only — no code change

Summary by CodeRabbit

• Documentation
  • Updated development guidelines to establish new requirements for code documentation standards.
  • Added corresponding documentation of the new guidelines in error reference materials.

[Copilot]

Pull request overview

This PR updates the repository’s AI guardrails documentation to require JSDoc headers on every new or modified function, and records the recurring mistake in ERRORS.md to reinforce the practice.

Changes:

• Add an ERRORS.md entry capturing the recurring “missing JSDoc on new functions” mistake.
• Add an always-on guardrail in .github/copilot-instructions.md requiring JSDoc (description, @param, and @returns guidance).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
ERRORS.md	Adds a new recurring-mistake entry about missing JSDoc headers on added functions.
.github/copilot-instructions.md	Adds a new guardrail requiring JSDoc on every new/modified function.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 89.85%. Comparing base (ecce8ee) to head (d1aa3ec).
⚠️ Report is 11 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #3143   +/-   ##
=======================================
  Coverage   89.85%   89.85%           
=======================================
  Files          52       52           
  Lines        1163     1163           
  Branches      233      233           
=======================================
  Hits         1045     1045           
  Misses        107      107           
  Partials       11       11           

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[PierreBrisorgueil]

@copilot review

[Copilot]

@PierreBrisorgueil I've opened a new pull request, #3144, to work on those changes. Once the pull request is ready, I'll request review from you.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

[PierreBrisorgueil]

@copilot review

[Copilot]

@PierreBrisorgueil I've opened a new pull request, #3145, to work on those changes. Once the pull request is ready, I'll request review from you.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[PierreBrisorgueil]

@copilot review

[Copilot]

@PierreBrisorgueil I've opened a new pull request, #3146, to work on those changes. Once the pull request is ready, I'll request review from you.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

[coderabbitai]

Warning

Rate limit exceeded

@PierreBrisorgueil has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 3 minutes and 1 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📝 Walkthrough

Walkthrough

Two documentation files were updated to establish a new policy requiring JSDoc headers for all new or modified functions, including @param entries for arguments and @returns entries for return values (mandatory for async functions).

Changes

Cohort / File(s)	Summary
Documentation & Policy Standards .github/copilot-instructions.md, ERRORS.md	Added new policy requirement that functions must include JSDoc headers with parameter and return value documentation. Documented in both the Copilot instructions and error catalog.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 With whiskers twitched and paws held high,
We document our functions well!
Each @param and @returns, oh my—
Our JSDoc tales now proudly tell.
Clear code hops forward, clear and spry! 🌟

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description covers Summary, Why, and Scope sections with clear details, but lacks Validation, Guardrails checks, and other template sections required for complete documentation.	Complete the description by adding Validation checklist items, Guardrails check items, and verifying all required template sections are addressed.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding a JSDoc enforcement rule to guardrails documentation for all new or modified functions.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch docs/enforce-jsdoc-on-functions

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[PierreBrisorgueil]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@ERRORS.md`:
- Line 14: The ERRORS.md entry currently says "functions: added functions
without JSDoc header -> always add JSDoc (description + `@param` + `@returns`)"
which contradicts the guardrail; update this entry to reference "new or modified
functions" instead of "added functions" so it matches the guardrail wording
(e.g., change the phrase "added functions" to "new or modified functions" while
preserving the rest of the guidance and the JSDoc requirements).

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.