docs: Comprehensive JSDoc annotation improvements across the SDK

[WhitWaldo]

Summary

The JS SDK currently has inconsistent and incomplete JSDoc annotations. Many public interfaces, methods, types, and type properties lack documentation, making it difficult for consumers to understand method signatures, expected inputs/outputs, and the purpose of configuration options without consulting external references or reading implementation code.

Motivation

• Developer experience: Good inline documentation enables IDE intellisense, hover-tooltips, and auto-generated API docs to surface meaningful information.
• Onboarding: New contributors and users should be able to understand what a method does, what its parameters mean, and what it returns without leaving their editor.
• API docs generation: Well-annotated code enables tools like TypeDoc to produce comprehensive reference documentation.
• Maintainability: Explicit documentation of contracts reduces ambiguity and prevents drift between intent and implementation.

Current State

A quick audit of the src/ directory reveals:

• Most interface methods (e.g., IClientActor, IClientState, IClientPubSub) have zero JSDoc annotations — no @param, @returns, @description, or @example tags.
• Type definitions (e.g., ActorReminderType, OperationType, KeyValueType) have minimal or no property descriptions.
• Some areas (workflow, pubsub) have partial documentation, but coverage is inconsistent.
• The Dapr Actors runtime classes (AbstractActor, ActorRuntime, ActorManager) have some JSDoc but it's incomplete.

Scope & Guidelines

What to annotate

1. All public interfaces (src/interfaces/):

   • Every method should have a @description explaining what it does
   • Every parameter should have a @param tag with its purpose and constraints
   • Every return should have a @returns tag explaining the response shape
   • Add @example tags for non-obvious usage patterns
   • Add @throws tags where methods can throw known error types
   • Add @see tags linking to relevant Dapr documentation

2. All exported types (src/types/):

   • Every property should have a description comment explaining its purpose, valid values, and defaults
   • Optional properties should note what happens when omitted

3. All public classes (DaprClient, DaprServer, DaprWorkflowClient, WorkflowRuntime, AbstractActor, etc.):

   • Class-level @description explaining the class's role
   • Constructor parameters documented
   • All public methods documented per the interface guidelines above

4. Enums (src/enum/):

   • Each enum value should have a brief description

Style conventions

• Use TypeScript-style JSDoc (/** ... */)
• Write descriptions in present tense, third person (e.g., "Invokes a method on the specified actor")
• Keep descriptions concise but complete
• Use @example blocks with realistic code snippets
• Reference Dapr concepts by linking to docs where helpful: @see https://docs.dapr.io/...
• For duration parameters that use Temporal.Duration, document the expected format (e.g., "ISO 8601 duration or a Temporal.Duration instance representing the interval between invocations")

Example of good annotation

/**
 * Registers a reminder for the specified actor instance.
 *
 * Reminders are durable, surviving actor deactivation and sidecar restarts.
 * They persist until explicitly unregistered or their TTL expires.
 *
 * @param actorType - The registered actor type name (e.g., "OrderActor")
 * @param actorId - The unique identifier of the actor instance
 * @param name - A unique name for the reminder within this actor instance
 * @param reminder - Configuration for the reminder's schedule and payload
 * @returns Resolves when the reminder has been successfully registered with the Dapr sidecar
 * @throws {Error} If the actor type is not registered or the sidecar is unavailable
 *
 * @example
 * ```ts
 * await client.actor.registerActorReminder(
 *   "OrderActor",
 *   new ActorId("order-123"),
 *   "shipment-check",
 *   { period: Temporal.Duration.from({ minutes: 5 }), dueTime: Temporal.Duration.from({ seconds: 30 }) }
 * );
 * ```
 *
 * @see https://docs.dapr.io/developing-building-blocks/actors/howto-actors/#actor-reminders
 */
registerActorReminder(actorType: string, actorId: ActorId, name: string, reminder: ActorReminderType): Promise<void>;