Skip to content

docs: Fix documentation links and add missing JSDoc comments - #1419

Merged
TimothyJones merged 2 commits into
mainfrom
claude/api-extractor-release-tags-wfmqhn
Aug 31, 2026
Merged

TimothyJones merged 2 commits into
mainfrom
claude/api-extractor-release-tags-wfmqhn

Conversation

@TimothyJones

Copy link
Copy Markdown
Member

Summary

This PR fixes broken documentation links and adds missing JSDoc comments to improve API documentation generation and clarity across the codebase.

Key Changes

  • Fixed namespace references in documentation: Updated incorrect mocks.* namespace references to interactions.* in JSDoc comments for function interaction classes (WillCallFunction, WillCallThrowingFunction, WillReceiveFunctionCall, WillReceiveHttpRequest)

  • Fixed class reference links: Corrected JSDoc link from matchers.internals.AnyMatcherWithExample to matchers.base.AnyMatcherWithExample in the AnyMatcher base class

  • Added missing JSDoc documentation: Added @public markers and descriptive comments to previously undocumented or partially documented types and functions:

    • PluginDslDeclaration - describes DSL class declarations
    • ParameterType - parameter type definitions
    • TypeContainer - complex type containers
    • MatcherReference - matcher identification
    • PassToMatcher - composite matcher support
    • isPassToMatcher() - type guard function
    • isTypeContainer() - type guard function
    • ParameterDeclaration - matcher parameter declarations
    • DslObjectDeclaration - object definitions
    • MatcherDslDeclaration - matcher DSL definitions
    • StateObjectDeclaration - state object definitions
    • InteractionDslDeclaration - interaction DSL definitions
  • Improved documentation clarity: Updated JSDoc comments to use inline code formatting and clearer references:

    • Changed {@link MatchContext#descendAndCheck} to backtick-formatted descendAndCheck on MatchContext
    • Changed {@link @contract-case/case-plugin-dsl-types#LookupableMatcher} to clearer inline reference
    • Added missing parameter descriptions in generated documentation
  • Updated API extractor configuration: Added message suppression for ae-unresolved-link warnings in case-definition-dsl to handle namespace re-export resolution limitations

  • Updated version: Bumped case-definition-dsl package version from 0.31.1 to 0.31.2

Notable Implementation Details

  • The documentation fixes ensure that generated API documentation (markdown and JSON) correctly references types and functions
  • JSDoc comments now consistently include @public markers for exported types to ensure proper visibility in generated documentation
  • The API extractor configuration change acknowledges a known limitation in rushstack's declaration reference resolver while maintaining validation through api-documenter

https://claude.ai/code/session_01JhUff3VLTEX3VSeyaFXTBi

claude and others added 2 commits August 31, 2026 13:36
In case-plugin-base:
- Add missing @public release tags to the DSL declaration types,
  providePluginContext, MockExecutor and ContractCaseDslPlugin
- Rewrite MatchContext#member links, which api-documenter rendered as
  empty text, to link to MatchContext with the method name in prose
- Replace the cross-package LookupableMatcher link with plain code text,
  as api-documenter cannot resolve references outside the package

In case-definition-dsl:
- Correct @link namespace paths: mocks.* -> interactions.* and
  matchers.internals.* -> matchers.base.*, so api-documenter now emits
  working links instead of warnings
- Suppress ae-unresolved-link, which false-positives on all links through
  the package's `import * as` namespaces (rushstack#1308); api-documenter
  still validates these links against the doc model

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JhUff3VLTEX3VSeyaFXTBi
@TimothyJones
TimothyJones enabled auto-merge (squash) August 31, 2026 14:59
@TimothyJones
TimothyJones merged commit 2bd4f48 into main Aug 31, 2026
15 checks passed
@TimothyJones
TimothyJones deleted the claude/api-extractor-release-tags-wfmqhn branch August 31, 2026 15:14
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.

2 participants