Feature: Add colorization to js doc comments

[timotheeguerin]

fix #1347

Add syntax highlighting to doc comments. Include the syntax definition for the tmlanguage as well as the semantic highlighting.

Try it in the playground

[github-actions]

Changes in this PR will be published to the following url to try(check status of TypeSpec Pull Request Try It pipeline for publish status):
Playground: https://cadlplayground.z22.web.core.windows.net/prs/2306/

Website: https://cadlwebsite.z1.web.core.windows.net/prs/2306/

[bterlson]

Sorry I missed this until now.

I love the colors, definitely. However, I am pretty concerned about coloring the jsdoc keys the same as keywords. In the context of the given example, model gets lost. But I think the problem is worse in model properties where the jsdoc keywords will be much more prominent than the property itself.

Is there another option that might make sense?

[bterlson]

Eh, looking at it again it looks ok for the model case. Maybe my concern is really just that member names aren't rendered differently and get lost in the list of comments and decorators.

[timotheeguerin]

Sorry I missed this until now.

I love the colors, definitely. However, I am pretty concerned about coloring the jsdoc keys the same as keywords. In the context of the given example, model gets lost. But I think the problem is worse in model properties where the jsdoc keywords will be much more prominent than the property itself.

Is there another option that might make sense?

there is definitely some other token we can use than keyword I was just trying to keep the same used in typescript

we could not special case the known ones so they all like th @example in the image above

[allenjzhang]

like the feature but not sure about the color choices. One of the key benefit for dev doc is to have comment color to allow eyes to easily differentiate between comments and code. So now we want to differentiate tokens in comments further, I would like to suggest color from a muted palette. Maybe from gray or darker (than comment green) green?

[timotheeguerin]

like the feature but not sure about the color choices. One of the key benefit for dev doc is to have comment color to allow eyes to easily differentiate between comments and code. So now we want to differentiate tokens in comments further, I would like to suggest color from a muted palette. Maybe from gray or darker (than comment green) green?

We don't really control the actual color. The only thing we can do is give a token for what that chunk of text is. It is then up to the theme to color it. Some theme support more or less coloring. I did give it a different token than keywords but it default to that kind. This is also the same tokenization as typescript does with JSDoc. We could default to another token than keyword but it would also either could be a incorrect meaning and result in completely different colors between themes.

[github-actions]

Changes in this PR will be published to the following url to try(check status of TypeSpec Pull Request Try It pipeline for publish status):
Playground: https://cadlplayground.z22.web.core.windows.net/prs/2306/

Website: https://tspwebsitepr.z5.web.core.windows.net/prs/2306/

[github-actions]

Changes in this PR will be published to the following url to try(check status of TypeSpec Pull Request Try It pipeline for publish status):
Playground: https://cadlplayground.z22.web.core.windows.net/prs/2306/

Website: https://tspwebsitepr.z5.web.core.windows.net/prs/2306/