Azure / Azure/typespec-azure

[typespec-ts] Inject guidance JSDoc for special parameters/operations (decimal, conditional headers)

Open
#4,777 0 comments 0 reactions 2 assignees Claimed by @kazrael2119 View on GitHub
emitter:typescript
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.