TypeScript: TypeScript class method decorator not rendering properly in version >= 1.63.2

Does this issue occur when all extensions are disabled?: Yes

VS Code Version: 1.63.2
OS Version: Darwin x64 20.6.0

Steps to Reproduce:

Write a JSDoc string with an example that involves a decorator:

class MyClass {
   /**
   * This is an example of a decorator.
   * 
   * @example
   * ```typescript
   * import { MyClass } from '@org/myClass';
   * 
   * const myClass = new MyClass();
   * 
   * class MyAwesomeClass {
   *   @myClass.decorateMethod()
   *   public doStuff() {
   *     ...
   *   }
   * }
   * 
   * ```
   * 
   * @decorator Class
   */
   public decorateMethod(): MyType {
     return (target, _propertyKey, descriptor) => {
       const originalMethod = descriptor.value;

       descriptor.value = ((event, context, callback) => {
         return originalMethod?.apply(target, [ event, context, callback ]);
       });

       return descriptor;
     };
   }
}

Use decorator / hover on method declaration:

As you can see from the screenshot above the example appears not to be rendered correctly with two main issues:

Decorator is rendered on a new line & wrapped with *
All code indentation after the decorator is lost

Before opening this issue I’ve searched the repo (& the TypeScript one) and found a series of other issues. Most of them have been closed as duplicates or as fixed but as the above shows the issue is still there. Examples:

If the issue has been indeed fixed, could you please take a second to clarify what’s the intended usage to allow VS Code to render decorators correctly? I’m aware that decorators are an experimental feature, if that’s the reason why this is not supported could you please state it?

Thanks in advance.

About this issue

Original URL
State: open
Created 2 years ago
Reactions: 5
Comments: 18 (4 by maintainers)

Commits related to this issue

chore: use secret magic to make decorator display better ref: https://github.com/microsoft/TypeScript/issues/47679#issuecomment-1763863693 — committed to cellularjs/cellularjs by great-elephant 8 months ago

Most upvoted comments

This is really stupid and bad, but I use invisible separator U+2063 “⁣” before “@” as workaround and it works fine.

rnln on Oct 16, 2023

JSDoc itself is still active, and the community has open issues for this:

https://github.com/jsdoc/jsdoc/issues/1521 https://github.com/jsdoc2md/jsdoc-to-markdown/issues/209

@hegemonic do you have any opinions on decorator support?

I believe we should all aim to be on the same page to avoid community fracture. It would be so much better to coalesce into a common future.

In the worst case, a tool like better-docs would have to take incompatible syntax and convert it to compatible syntax, which wouldn’t be ideal.

trusktr on Jan 2, 2023

Decorators are non-experimental now with TypeScript 5. Can we have this fix soon pleeease? 🙏

trusktr on Sep 25, 2023

better-docs is a sweet JSDoc parser and generator for TypeScript, backward compatible with the original JSDoc.

https://github.com/SoftwareBrothers/better-docs

@wojtek-krysiak do you have any thoughts on how to handle decorators?

I think it would make sense to ensure that TypeScript’s format aligns well with the best tools in the community (like better-docs).

Better docs is great because it takes TypeScript code (with JSDoc) and can output 100% actual-JSDoc compatible JSDoc comments for compatibility with official JSDoc tooling, whereas other tools like TSDoc are not compatible.

trusktr on Oct 1, 2022

I think a solution should work with both code fences, and @example blocks.

Personally I think GitHub has the best handling of back ticks. Might be worth looking at.

But if back ticks can’t be fixed, I think at least \@ inside of an @example block (or anywhere) should just display @ as a single character.

Another option for escaping @ could be to write one double: @@.

JSDoc was designed before the language had decorators, so I think anything goes here really.

trusktr on Oct 1, 2022

Update: the fix at #50677 correctly makes single and triple backticks multiline, but this breaks unclosed backticks in the tests and would break them in the compiler source code itself. We’re discussing whether to take the change or not.

sandersn on Sep 12, 2022