Grats author here. I agree, decorators would be preferable. However, decorators are a runtime construct and as such cannot be applied to type constructs. This means you can’t, for example, annotate an interface definition, or add a description to an argument (since arguments are declared using an object type literal).

You can read more about how I ended up settling on docblocks here: https://grats.capt.dev/docs/faq/why-use-comments

I don't think they'd work with TypeScript types because the types aren't actually retained in the compiled JavaScript but I agree. It seems kind of like a hack - usually you assume that comments aren't going to be executed or affect anything when the code is run, so it doesn't feel right when you use them to generate code.

The docs have a page [0] addressing this question. The tl;dr is because grats uses the TypeScript compiler to parse an AST, and the compiler already recognizes docblocks and attaches them to AST nodes.

[0] https://grats.capt.dev/docs/faq/why-use-comments