[TCGC] How to manage language-specific decorators
- Dominant language
- TypeScript
- Stars
- 27
- Forks
- 90
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 156
Description
We have some decorators which only apply to one or two languages, like `@deserializeEmptyStringAsNull` only for Csharp. There are two issues introduced:
- Without clearly [documented](https://azure.github.io/typespec-azure/docs/libraries/typespec-client-generator-core/reference/decorators/#@Azure.ClientGenerator.Core.deserializeEmptyStringAsNull) customers may not know the valid scopes for this
- Even we have that, we don't have any linters to limit the decorator to specific scopes. Customers could write code with wrong scopes.
Regardless of the option chosen, we need to update the documentation to include supported scopes. This will help customers understand the valid scopes for each decorator.
**Option 1 - Make decorator scopes as required**
This option involves making the scope parameter a required field. This approach ensures that the decorator is only applied to supported languages.
Current Interface:
```ts
@Azure.ClientGenerator.Core.deserializeEmptyStringAsNull(scope?: valueof string);
@Azure.ClientGenerator.Core.protocolAPI(flag?: valueof boolean, scope?: valueof string);
```
Here is the proposed interface. If the decorator would only be specified to 1 or 2 languages we would
- adjust the parameter order to put it in required ones
- limit the scopes to supported languages only
```ts
@Azure.ClientGenerator.Core.deserializeEmptyStringAsNull(scope: valueof "csharp");
@Azure.ClientGenerator.Core.protocolAPI(scope: valueof "java" | "csharp", flag?: valueof boolean);
```
Implications
- Breaking Changes: Existing specifications will break due to the change from optional to required parameters and the adjustment of parameter positions.
- Future Expansion: If the scope is expanded to all languages, the parameter will need to revert to optional, potentially causing further breaking changes.
**Option 2 - Report warnings**
This option maintains the current interface but introduces warnings when unsupported language scopes are specified. This approach avoids breaking changes.
Benefits
- No Breaking Changes: The interface remains the same, avoiding disruptions to existing specifications.
- Guidance Through Warnings: Customers receive warnings if they specify unsupported language scopes, guiding them to correct usage.
**In-scoped decorators**
Here are the decorators which may be impacted:
- https://azure.github.io/typespec-azure/docs/libraries/typespec-client-generator-core/reference/decorators/#@Azure.ClientGenerator.Core.protocolAPI
- https://azure.github.io/typespec-azure/docs/libraries/typespec-client-generator-core/reference/decorators/#@Azure.ClientGenerator.Core.convenientAPI
- https://azure.github.io/typespec-azure/docs/libraries/typespec-client-generator-core/reference/decorators/#@Azure.ClientGenerator.Core.deserializeEmptyStringAsNull
- https://azure.github.io/typespec-azure/docs/libraries/typespec-client-generator-core/reference/decorators/#@Azure.ClientGenerator.Core.useSystemTextJsonConverter
Contributor guide
Research direction
Start with the four linked decorator reference pages and review how each decorator currently documents its scope and signature. Resolve whether the project should require supported scopes or emit warnings, then update the affected documentation and any related validation; done means all listed decorators clearly identify valid language scopes and the chosen behavior is covered.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100