[typespec-ts] Inject guidance JSDoc for special parameters/operations (decimal, conditional headers)
- Dominant language
- TypeScript
- Stars
- 27
- Forks
- 90
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 156
Description
## Overview
Enhance the TypeScript emitter (`@azure-tools/typespec-ts`) to automatically inject standardized **guidance JSDoc** for certain parameter and operation types, warning SDK consumers about JavaScript-specific pitfalls and service behaviors. Migrated from [Azure/autorest.typescript](https://github.com/Azure/autorest.typescript), which is being retired in favor of this repo.
## Work items
### 1. JSDoc for `decimal` input parameters
Detect `decimal` / `decimal128` parameters and inject a JSDoc block warning about IEEE-754 floating-point rounding (e.g. `0.1 + 0.2 !== 0.3`) with mitigation guidance (integer math / decimal library).
Proposed template:
```typescript
/**
* @param value - A decimal number.
* **Important:** JavaScript uses IEEE 754 floating-point arithmetic, which can introduce
* rounding errors for decimal values (e.g., 0.1 + 0.2 !== 0.3).
*
* To avoid precision issues:
* - Use integer math for fixed-point values (e.g., represent cents instead of dollars).
* - Or use a decimal library (e.g., `decimal.js`) for exact calculations.
*/
```
- Migrated from Azure/autorest.typescript#3611
### 2. JSDoc for conditional request headers
Detect operations that support conditional headers (`If-Match`, `If-None-Match`, `If-Modified-Since`, `If-Unmodified-Since`) and inject a JSDoc block explaining `412 Precondition Failed` / `304 Not Modified` behavior and that the SDK does not auto-retry/resolve conflicts.
Proposed template:
```typescript
/**
* **Important:** If you set conditional headers (e.g., `If-Unmodified-Since`, `If-Match`),
* the service may return:
* - `412 Precondition Failed` if the resource changed since the specified condition.
* - `304 Not Modified` for GET requests if the resource has not changed.
*
* The SDK does not automatically retry or resolve conflicts.
* You should handle these status codes in your application logic.
*/
```
- Migrated from Azure/autorest.typescript#3612
## Acceptance criteria
- [ ] Generator detects `decimal`/`decimal128` input parameters and injects the decimal JSDoc.
- [ ] Generator detects operations with conditional headers and injects the conditional-header JSDoc.
- [ ] Templates applied consistently across generated methods/interfaces.
- [ ] Unit tests verify the generated JSDoc blocks.
- [ ] Does not break existing linting/formatting rules.
## Notes
- Consider making the JSDoc templates configurable.
- Test coverage is tracked as part of each item above, not as standalone issues.
Contributor guide
Assessment
This issue has not been assessed yet.