docs(jsdoc): Phase 6 — Annotate utility modules and internal helpers
- Dominant language
- JavaScript
- Stars
- 217
- Forks
- 104
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
Add JSDoc annotations to the utility and helper modules that support the SDK's core functionality. While these are mostly internal, they are imported across the codebase and some are transitively exposed to consumers. Good documentation here aids maintainability and contributor onboarding.
## Scope
### Utilities (`src/utils/`)
| File | Purpose |
|------|---------|
| `Actors.util.ts` | Actor-related helpers (ID generation, type resolution) |
| `Client.util.ts` | Client creation helpers, option merging |
| `CloudEvent.util.ts` | CloudEvents v1.0 envelope construction |
| `Deserializer.util.ts` | Response deserialization logic |
| `HttpVerb.util.ts` | HTTP method enum/helpers |
| `Map.util.ts` | Map/object conversion utilities |
| `NodeJS.util.ts` | Node.js version/environment detection |
| `Serializer.util.ts` | Request serialization logic |
| `Settings.util.ts` | Default settings and environment variable resolution |
| `Streams.util.ts` | Stream processing utilities |
### Logger (`src/logger/`)
- `Logger.ts` — SDK logger implementation
- `ConsoleLoggerService.ts` — Default console-based logger
### Pub/Sub internals (`src/pubsub/`)
- `subscriptionManager.ts` — Runtime subscription tracking
### Enums (`src/enum/`)
- `HttpStatusCode.enum.ts` — HTTP status code constants
- `SubscribedMessageHttpResponse.enum.ts` — PubSub message acknowledgement values
## Requirements
- [ ] Every exported function: `@description`, `@param`, `@returns`
- [ ] Every exported constant/enum: description of purpose and each value
- [ ] `CloudEvent.util.ts`: Document CloudEvents spec compliance and field mappings
- [ ] `Settings.util.ts`: Document each environment variable read, its default, and override behavior
- [ ] `Serializer.util.ts` / `Deserializer.util.ts`: Document serialization format expectations
- [ ] Logger: Document log levels, how to provide custom logger implementations
- [ ] Internal functions that are non-obvious: brief inline documentation
## Example
```ts
/**
* Resolves the effective Dapr host from options or environment.
*
* Resolution order:
* 1. Explicit `host` option if provided
* 2. `DAPR_HOST` environment variable
* 3. Default: `"127.0.0.1"`
*
* @param options - Client options that may contain an explicit host
* @returns The resolved host address
*/
export function getDaprHost(options?: { daprHost?: string }): string { ... }
```
## Acceptance Criteria
- [ ]All exported utility functions annotated
- [ ] All enums and constants documented
- [ ] Logger and serialization modules documented
- [ ] Environment variable behavior documented in Settings
- [ ] No logic changes — documentation only
- [ ] Builds cleanly (npm run build)
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.