microsoft / microsoft/typespec
Multiple doc comment on the same node
- Dominant language
- Java
- Stars
- 5.9k
- Forks
- 394
- Avg merge
- 1d 23h
- Merged PRs (30d)
- 104
Description
If you have multiple doc comment on the same node it combines things right now, which result in maybe confusing docs
```tsp
/** one */
/** two */
model Test {}
```
```yaml
components:
schemas:
Test:
type: object
description: onetwo
```
[Playground](https://cadlplayground.z22.web.core.windows.net/?c=LyoqIG9uZSAqLwrEC3R3b8QLbW9kZWwgVGVzdCB7fQ%3D%3D&e=@typespec/openapi3&options=%7B%7D)
Note that this is in no way something we'd expect people to be doing(and maybe we could lint it) but as you are typing your typespec you could endup with this if you start with adding the doc comment before a property and now the info gets tagged on the next node.
Typescript on the other end just always take the last one. So in example above it would just show `two` as the doc
This is the case also when involving `@param` it won't merge the params from both docs, the 1st one is basically ignored.
```tsp
/**
* This is the 1st
* @param a This is A 1
* @param b This is only doc here
*/
/**
* This is the 2nd
* @param a This is A 2
*/
function foo(a: string, b: string) {}
// Here b has no doc
```
Contributor guide
Assessment
This issue has not been assessed yet.