microsoft / microsoft/typespec

Multiple doc comment on the same node

Open
#2,421 0 comments 0 reactions 0 assignees View on GitHub
bug triaged:core
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
image

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

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.