powertools-lambda-typescript (all): JSDoc for method decorators don't render properly

(all): JSDoc for method decorators don't render properly

Open dreamorosi opened this issue 2 years ago • 2 comments

Description of the improvement

Summary of the proposal Currently hovering on a decorator in VS Code shows an unindented code example with also additional characters (*) around the decorator name. This, aside from the fact that decorators are still experimental in TypeScript, is probably due to either the @ sigil conflicting with JSDocs (which uses the same symbol to delimit sections) and/or VS Code itself.

Discussion of the issue here.

TODO:

[ ] Create isolated code sample
[ ] Test if this is an issue in other IDEs (like the IntelliJ ones)
[ ] Open an issue on the TS or VS Code repos

How, where did you look for information Hover on a decorator while on VS Code.

Missing or unclear documentation N/A

Improvement The code example should be indented & highlighted/rendered properly.

Related issues, RFCs

N/A

Dec 12 '21 15:12 dreamorosi

Opened issue on the VS Code repo: microsoft/TypeScript#47679

Jan 31 '22 10:01 dreamorosi

Update on the above:

The issue on the TS repo was initially included in the TypeScript 4.7.0 milestone but it has now been rescheduled as part of the 4.8.0 milestone (link).

The milestone is, at the time of writing this, at 2% completion and includes north of 350 issues.

May 16 '22 11:05 dreamorosi

The issue still persists, however it appears that using an invisible character (U+2063) in front of the @ forces the IDE to display the decorator properly.

This is not an ideal solution, however we can adopt this workaround so that customers can consume the docstrings and have them rendered correctly.

I am subscribed to the upstream issue and will keep an eye on it, if a proper fix is released I'll remove the invisible character.

Oct 18 '23 17:10 dreamorosi

⚠️ COMMENT VISIBILITY WARNING ⚠️

Comments on closed issues are hard for our team to see. If you need more assistance, please either tag a team member or open a new issue that references this one. If you wish to keep having a conversation with other community members under this issue feel free to do so.