Add JSDoc annotations to enable auto-generated API docs and type definitions

[oberstet]

Summary

Add comprehensive JSDoc annotations to the AutobahnJS source code to enable:

1. Auto-generated API documentation via sphinx-js
2. TypeScript .d.ts type definition generation (Track A from AutobahnJS v26.1.1 Release #595)

Background

The v26.1.1 documentation infrastructure uses Sphinx with the Furo theme, deployed to GitHub Pages. We initially planned to use sphinx-js for auto-generated JavaScript API documentation, but this requires JSDoc annotations in the source code.

Currently, the AutobahnJS codebase has minimal JSDoc comments. The docs/api/index.rst was converted to a manual API reference as a workaround (see commit 39e4f18).

Relationship to Track A: Type Definitions (#595)

JSDoc annotations are a prerequisite for Track A.

From #595, Track A's approach is:

• Generate .d.ts type definition files from existing code
• Add JSDoc type annotations where missing
• Configure TypeScript in checkJs mode for validation
• Do NOT rewrite codebase in TypeScript (high risk)

JSDoc annotations serve dual purposes:

Purpose	Tool	Benefit
API Documentation	sphinx-js	Auto-generated docs from source
Type Definitions	TypeScript (tsc --declaration)	Generate .d.ts files from JSDoc
Static Analysis	TypeScript (checkJs mode)	Type checking without migration

By adding JSDoc annotations, we enable both goals with a single effort:

• sphinx-js reads JSDoc to generate Sphinx documentation
• TypeScript reads JSDoc to generate .d.ts type definitions
• TypeScript can validate types in CI without converting to .ts files

Scope

Files to Annotate

Priority 1: Public API (packages/autobahn/lib/)

• connection.js — Connection class, options, callbacks
• session.js — Session class, RPC/PubSub methods
• autobahn.js — Main exports
• serializer.js — Serializer classes
• auth_cra.js — WAMP-CRA authentication

Priority 2: Internal Classes

• transport/websocket.js — WebSocket transport
• transport/rawsocket.js — RawSocket transport
• util.js — Utility functions
• log.js — Logging

Priority 3: XBR Extension (packages/autobahn-xbr/lib/)

• autobahn-xbr.js — XBR exports
• buyer.js, seller.js — Market participants
• eip712.js — Ethereum signing

JSDoc Coverage Required

/**
 * Manages WebSocket connection and WAMP session lifecycle.
 * @class
 * @param {Object} options - Connection options
 * @param {string} options.url - WebSocket URL (e.g., 'ws://localhost:8080/ws')
 * @param {string} options.realm - WAMP realm to join
 * @param {string[]} [options.authmethods] - Authentication methods
 * @param {string} [options.authid] - Authentication ID
 * @param {Function} [options.onchallenge] - Challenge callback
 * @param {number} [options.max_retries=15] - Maximum reconnection attempts
 * @example
 * const connection = new autobahn.Connection({
 *     url: 'ws://localhost:8080/ws',
 *     realm: 'realm1'
 * });
 */
function Connection(options) {
    // ...
}

/**
 * Open the connection to the WAMP router.
 * @returns {void}
 */
Connection.prototype.open = function() {
    // ...
};

Implementation Plan

Phase 1: Core Public API

1. Annotate Connection class with all options
2. Annotate Session class with RPC/PubSub methods
3. Annotate serializer classes
4. Annotate authentication functions
5. Re-enable sphinx-js in docs/conf.py
6. Verify docs build with auto-generated API

Phase 2: Type Definition Generation

1. Add tsconfig.json with allowJs, checkJs, declaration options
2. Run tsc --declaration to generate .d.ts files
3. Add .d.ts files to npm package
4. Add TypeScript validation to CI

Phase 3: Internal Classes & XBR

1. Annotate transport classes
2. Annotate utility functions
3. Annotate XBR extension classes

Acceptance Criteria

• All public API functions/classes have JSDoc annotations
• sphinx-js generates API docs without errors
• TypeScript can generate .d.ts files from JSDoc
• tsc --checkJs passes in CI
• npm package includes .d.ts type definitions

References

• JSDoc documentation
• TypeScript JSDoc Reference
• sphinx-js
• Track A in AutobahnJS v26.1.1 Release #595: Type definitions (.d.ts files)
• Docs build workaround: commit 39e4f18

Target

v26.2.1 or later — This is foundational work that enables both improved documentation and Track A type definitions.

[markope]

I just wanted to create an issue to request type declarations in the bundle and saw this issue here. So my interest here is to use the bundled autobahn type declarations for intellisense and type checking in my own code.

See as well my comment on vite-plugin-dts here #601

[oberstet]

Yes — we do absolutely want to provide a modern, typed user-facing API for AutobahnJS 👍

However, since AutobahnJS is currently implemented in plain JavaScript, the correct and lowest-risk way to do this is to hand-author TypeScript declaration files (.d.ts) for the public API, rather than trying to auto-generate them.

Automated tooling (like tsc --declaration or Vite plugins) fundamentally relies on TypeScript source code or very heavily annotated JSDoc. Without that, such tools cannot accurately or safely infer a complex API like AutobahnJS’.

Manually written typings also have the advantage that they act as a stable public contract: we can precisely model the supported API surface (sessions, procedures, subscriptions, promises, callbacks, etc.) without refactoring runtime code or risking regressions.

A full TypeScript rewrite is not off the table long-term, but it would be a significant effort with non-trivial risk for a mature, protocol-heavy library. Providing high-quality handwritten typings gives users immediate benefit while keeping the implementation stable.