microsoft / microsoft/typespec
[doc] enhance the usage document of @doc
- Dominant language
- Java
- Stars
- 5.9k
- Forks
- 394
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 104
Description
There has a user trying to parameterize an interface doc decorator but running into an issue.
```typespec
const DeploymentStackCommonOpDefaultParams: Record = #{
ScopeName: "resource scope" // resource group, subscription, etc
};
// Generic interface for common DeploymentStack operations
// For some reason, the ArmResourceActionAsync type requires the base params extends this reflection model type.
interface DeploymentStackCommonOps = DeploymentStackCommonOpDefaultParams> {
/**
* Gets a Deployment stack with a given name at the specified scope.
*/
@doc("Gets a Deployment stack with the given name in the {ScopeName}", VCommonOpsParams)
get is ArmResourceRead;
```
```plain text
Argument of type 'VCommonOpsParams' is not assignable to parameter of type '{}'TypeSpec(invalid-argument)
Argument of type '#{ScopeName: "resource group"}' is not assignable to parameter of type '{}'TypeSpec(invalid-argument)
Argument of type 'unknown' is not assignable to parameter of type '{}'TypeSpec(invalid-argument)
Argument of type 'unknown' is not assignable to parameter of type '{}'TypeSpec(invalid-argument)
```
The expert answer is:
```plain text
That parameter is a legacy thing that doesn't do what you would think it does. It interpolate the internal properties of the type passed. It is currently exclusively used for interpolating the name of models in templates.
You can't create an option bag today but you can just interpolate values with ${} directly
```
Could we add this kind of usage for @doc document?
Contributor guide
Assessment
This issue has not been assessed yet.