fix: add deprecation tag for h3 and hono JSDoc

[kazupon]

Description

Linked Issues

Additional context

Summary by CodeRabbit

• Documentation
  • Multiple locale utility functions have been marked as deprecated and will be removed in a future release. Users are directed to use equivalent utilities from the @intlify/utils package instead.

[coderabbitai]

Walkthrough

This PR systematically marks 13 locale-related functions as deprecated across the h3 and hono adapters by adding deprecation notices to JSDoc comments in source files and striking through function documentation with corresponding "Deprecated" sections, directing users to equivalent utilities from @intlify/utils since v2.

Changes

Cohort / File(s)	Summary
H3 Function Documentation docs/h3/functions/getCookieLocale.md, docs/h3/functions/getHeaderLanguage.md, docs/h3/functions/getHeaderLanguages.md, docs/h3/functions/getHeaderLocale.md, docs/h3/functions/getHeaderLocales.md, docs/h3/functions/getPathLocale.md, docs/h3/functions/getQueryLocale.md, docs/h3/functions/setCookieLocale.md, docs/h3/functions/tryCookieLocale.md, docs/h3/functions/tryHeaderLocale.md, docs/h3/functions/tryHeaderLocales.md, docs/h3/functions/tryPathLocale.md, docs/h3/functions/tryQueryLocale.md	Function headers rendered as struck-through; new "Deprecated" sections added indicating deprecation since v2 and directing to @intlify/utils equivalents
Hono Function Documentation docs/hono/functions/getCookieLocale.md, docs/hono/functions/getHeaderLanguage.md, docs/hono/functions/getHeaderLanguages.md, docs/hono/functions/getHeaderLocale.md, docs/hono/functions/getHeaderLocales.md, docs/hono/functions/getPathLocale.md, docs/hono/functions/getQueryLocale.md, docs/hono/functions/setCookieLocale.md, docs/hono/functions/tryCookieLocale.md, docs/hono/functions/tryHeaderLocale.md, docs/hono/functions/tryHeaderLocales.md, docs/hono/functions/tryPathLocale.md, docs/hono/functions/tryQueryLocale.md	Function headers rendered as struck-through; new "Deprecated" sections added indicating deprecation since v2 and directing to @intlify/utils equivalents
Index Documentation docs/h3/index.md, docs/hono/index.md	Function table entries replaced with struck-through link versions to indicate deprecated status
Source JSDoc Deprecation Notices src/h3.ts, src/hono.ts	JSDoc comments added to exported functions marking them deprecated since v2 and recommending @intlify/utils alternatives

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

• Areas requiring attention:
  • Verify consistency of deprecation messaging across all 26+ documentation files (identical guidance pointing to @intlify/utils)
  • Confirm JSDoc deprecation notices in source files match documentation wording
  • Spot-check that no functional code logic changes were inadvertently introduced
  • Validate struck-through formatting applied correctly to all function names in both h3 and hono docs

Possibly related PRs

• feat!: warning for h3 and hone utils #70: Complements this deprecation by adding runtime warnOnce calls for the same functions to surface deprecation warnings at runtime, while this PR marks them as deprecated in documentation.
• fix: wrong default options #65: Refactors the signatures of these same locale helper functions to use a single options object pattern, representing a structural evolution of the utilities being deprecated here.

Poem

🐰 The functions rest, struck through with care,
A gentle nudge to utils there,
Since v2 came with changes new,
@intlify shows what's true,
Deprecated but not forgotten, dear! ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding deprecation tags to JSDoc comments in h3 and hono source files, along with updating documentation files to mark these functions as deprecated.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/jsdoc-deprecated

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between d56b3d4 and e98eeda.

📒 Files selected for processing (30)

• docs/h3/functions/getCookieLocale.md (2 hunks)
• docs/h3/functions/getHeaderLanguage.md (2 hunks)
• docs/h3/functions/getHeaderLanguages.md (2 hunks)
• docs/h3/functions/getHeaderLocale.md (2 hunks)
• docs/h3/functions/getHeaderLocales.md (2 hunks)
• docs/h3/functions/getPathLocale.md (2 hunks)
• docs/h3/functions/getQueryLocale.md (2 hunks)
• docs/h3/functions/setCookieLocale.md (2 hunks)
• docs/h3/functions/tryCookieLocale.md (2 hunks)
• docs/h3/functions/tryHeaderLocale.md (2 hunks)
• docs/h3/functions/tryHeaderLocales.md (2 hunks)
• docs/h3/functions/tryPathLocale.md (2 hunks)
• docs/h3/functions/tryQueryLocale.md (2 hunks)
• docs/h3/index.md (1 hunks)
• docs/hono/functions/getCookieLocale.md (2 hunks)
• docs/hono/functions/getHeaderLanguage.md (2 hunks)
• docs/hono/functions/getHeaderLanguages.md (2 hunks)
• docs/hono/functions/getHeaderLocale.md (2 hunks)
• docs/hono/functions/getHeaderLocales.md (2 hunks)
• docs/hono/functions/getPathLocale.md (2 hunks)
• docs/hono/functions/getQueryLocale.md (2 hunks)
• docs/hono/functions/setCookieLocale.md (2 hunks)
• docs/hono/functions/tryCookieLocale.md (2 hunks)
• docs/hono/functions/tryHeaderLocale.md (2 hunks)
• docs/hono/functions/tryHeaderLocales.md (2 hunks)
• docs/hono/functions/tryPathLocale.md (2 hunks)
• docs/hono/functions/tryQueryLocale.md (2 hunks)
• docs/hono/index.md (1 hunks)
• src/h3.ts (13 hunks)
• src/hono.ts (13 hunks)

🔇 Additional comments (32)

docs/h3/functions/getHeaderLanguage.md (1)

7-7: Deprecation signaling is clear and consistent.

The strike-through function header and new Deprecated section follow the expected pattern. The migration message is specific and actionable.

Also applies to: 48-50

docs/hono/functions/setCookieLocale.md (1)

7-7: Consistent deprecation messaging.

Properly marks the function as deprecated with clear migration guidance to @intlify/utils.

Also applies to: 49-51

docs/hono/functions/tryHeaderLocale.md (1)

7-7: Consistent with deprecation pattern.

Also applies to: 32-34

docs/h3/functions/getHeaderLocales.md (1)

7-7: Consistent deprecation signaling.

Also applies to: 51-53

docs/h3/functions/getPathLocale.md (1)

7-7: Clear deprecation notice.

Also applies to: 32-34

docs/hono/functions/tryHeaderLocales.md (1)

7-7: Deprecation pattern applied consistently.

Also applies to: 32-34

docs/hono/functions/tryPathLocale.md (1)

7-7: Deprecation signaling properly applied.

Also applies to: 32-34

docs/hono/index.md (1)

21-33: Index-level deprecation marking is comprehensive and clear.

All 13 functions are consistently marked as deprecated through strike-through formatting. This ensures users browsing the index immediately understand that these functions are deprecated and should use @intlify/utils alternatives.

docs/h3/functions/getHeaderLanguages.md (1)

7-7: Deprecation markup is consistent and clear.

The strikethrough header and new Deprecated section follow the expected documentation pattern. Message clearly directs users to the @intlify/utils equivalent.

Also applies to: 48-50

docs/hono/functions/getHeaderLocales.md (1)

7-7: Consistent deprecation format across documentation.

The strikethrough and Deprecated section follow the established pattern. Messaging is clear and actionable.

Also applies to: 52-54

docs/h3/functions/tryQueryLocale.md (1)

7-7: Documentation deprecation is properly formatted.

Strikethrough and Deprecated section follow the established pattern consistently.

Also applies to: 32-34

src/hono.ts (2)

59-60: All 13 deprecated functions have consistent JSDoc tags and runtime warnings.

Every deprecated function follows the pattern:

• @deprecated since v2. Use <functionName> of @intlify/utils instead. in JSDoc
• warnOnce() call at function entry for runtime feedback

This ensures both static (IDE hints, linters) and dynamic (console warnings) deprecation signals. The message consistency and completeness are excellent.

Also applies to: 95-96, 132-133, 152-153, 195-196, 223-224, 265-266, 286-287, 326-327, 352-353, 372-373, 396-397, 417-418

---

28-28: Verify warnOnce utility is appropriate for deprecation warnings.

The warnOnce() calls prevent log spam from repeated invocations. Ensure this utility uses console.warn() or similar visible-by-default output (not console.debug()) so users notice deprecation messages during development.

docs/hono/functions/getCookieLocale.md (1)

7-7: Documentation deprecation follows established pattern.

Consistent formatting and messaging across the h3/hono documentation suite.

Also applies to: 48-50

docs/h3/functions/setCookieLocale.md (1)

7-7: Documentation deprecation markup is correct.

Consistent with other updated documentation files.

Also applies to: 48-50

docs/hono/functions/getPathLocale.md (1)

7-7: Deprecation documentation is properly formatted.

Consistent with the rest of the PR changes.

Also applies to: 32-34

docs/h3/functions/getQueryLocale.md (1)

7-7: Deprecation formatting is consistent and correct.

All documentation changes follow the established pattern throughout the PR.

Also applies to: 32-34

docs/h3/functions/tryHeaderLocale.md (1)

7-7: LGTM! Documentation deprecation is clear.

The strikethrough formatting and deprecation notice properly signal that this function is deprecated since v2, with clear guidance to use the equivalent from @intlify/utils.

Also applies to: 32-34

docs/h3/functions/getCookieLocale.md (1)

7-7: LGTM! Deprecation notice is consistent.

The documentation follows the same deprecation pattern as other functions in the PR, clearly marking the function as deprecated and directing users to the replacement.

Also applies to: 47-49

docs/hono/functions/getHeaderLocale.md (1)

7-7: LGTM! Hono function deprecation is properly documented.

The deprecation formatting is consistent with the h3 variants, providing clear guidance for migration to @intlify/utils.

Also applies to: 52-54

docs/hono/functions/getHeaderLanguages.md (1)

7-7: LGTM! Deprecation is clearly communicated.

The documentation properly marks the function as deprecated and provides the migration path to the equivalent utility.

Also applies to: 48-50

docs/hono/functions/tryQueryLocale.md (1)

7-7: LGTM! Deprecation notice is consistent.

The documentation follows the established pattern, clearly marking the function as deprecated with proper migration guidance.

Also applies to: 32-34

src/h3.ts (2)

63-77: LGTM! Well-implemented deprecation pattern.

The deprecation approach is excellent:

• JSDoc @deprecated tag provides IDE/editor warnings
• Runtime warnOnce() ensures developers see deprecation notices without console spam
• Function behavior unchanged, maintaining backward compatibility during migration period
• Clear guidance pointing to the replacement in @intlify/utils

This pattern is consistently applied across all 13 deprecated functions in this file.

---

104-112: All replacement functions verified in @intlify/utils.

Verification confirms all 13 functions referenced in the deprecation messages exist as exports in @intlify/utils (across src/web.ts, src/node.ts, src/http.ts, and their deno equivalents). The migration path is valid, and the consistent deprecation pattern across all functions (lines 104–436) properly guides users to supported alternatives.

docs/h3/functions/tryCookieLocale.md (1)

7-7: LGTM! Documentation deprecation is properly formatted.

The deprecation notice follows the consistent pattern used throughout the PR, clearly communicating the migration path to users.

Also applies to: 32-34

docs/hono/functions/getQueryLocale.md (1)

7-7: LGTM! Final documentation file maintains consistency.

The deprecation formatting is consistent with all other files in this PR, providing clear guidance for users migrating to @intlify/utils.

Also applies to: 32-34

docs/h3/functions/tryPathLocale.md (1)

7-7: LGTM - Deprecation formatting is consistent and clear.

The deprecation markup follows the established pattern: strikethrough header with a dedicated Deprecated section that clearly directs users to the equivalent utility in @intlify/utils. The function name referenced in the deprecation message matches the documented function.

Also applies to: 32-34

docs/h3/functions/tryHeaderLocales.md (1)

7-7: LGTM - Consistent deprecation formatting across h3 functions.

Function name in deprecation message correctly uses the plural form tryHeaderLocales matching the actual function, consistent with the established pattern from other files.

Also applies to: 32-34

docs/h3/functions/getHeaderLocale.md (1)

7-7: Minor inconsistency: Example import path may need clarification.

The documentation correctly marks the function as deprecated with proper strikethrough and deprecation section. However, note that the example code (line 38) imports from @intlify/utils/h3, while this h3-specific function is being deprecated in favor of the equivalent in @intlify/utils. The deprecation message should clarify whether users should import from @intlify/utils/h3 or just @intlify/utils post-migration.

Also applies to: 51-53

docs/hono/functions/getHeaderLanguage.md (1)

7-7: LGTM - Consistent deprecation pattern for hono namespace.

Deprecation formatting matches the h3 functions. Function name is correct and clearly directs to @intlify/utils equivalent.

Also applies to: 48-50

docs/h3/index.md (1)

21-33: LGTM - Comprehensive deprecation coverage in h3 index.

All 13 locale-related functions are marked as deprecated in the index table with strikethrough formatting, maintaining link functionality while clearly indicating deprecation status. This provides good visibility for users browsing the API reference.

docs/hono/functions/tryCookieLocale.md (1)

7-7: LGTM - Deprecation formatting consistent across hono functions.

The hono-specific tryCookieLocale function is properly deprecated with clear redirection to the @intlify/utils equivalent. The description helpfully clarifies the non-throwing behavior by returning null instead.

Also applies to: 32-34

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/intlify/utils/@intlify/utils@71

commit: e98eeda