Gauging interest on outputting certain ReScript comments to JS

1

One of the things we don’t transport over to the JS output is comments. Depending on the complexity, we might be able to bring some of those over depending on the ROI. We’d like to know whether there’s good use-cases for them.

Note:

  • We’ll only be able to do it selectively, e.g. letting you write a comment on top of a function and having it carried over to the outputted JS function. The compiler does some optimizations and shuffling, so we won’t have a generalized mechanism for you to output arbitrary comments in any place.
  • It’s easy to do for functions. Harder for let bindings.
  • It’s already possible, albeit slightly contrived, to output %%raw doc comments, but only to the top of the file: demo.
  • If you want to output some type annotations as comments for e.g. TypeScript, consider whether genType solves your issue already.
1 Like
2

Would it be weird to limit this to interface files? Since they are mostly where external exports will be located and which are probably that you want to document to external users?

1 Like
3

Perhaps this could leverage the “retain attribution comment” style supported by JavaScript minification tools?
/*! attribution comment */

Although that tends to be used as a bundle banner, not in every file. Still, it might be handy for library authors or projects where every source file has an attribution banner.

4

Kinda weird, and also kinda more work for less benefit than just opening it more.

That use-case’s solved by the linked demo =)

But we’re interested in more of these real-world use-cases.

5

Oh sorry yes I should have explained it was an off topic question. I wasn’t trying to demonstrate a use case, just speculate about doing this with attribution syntax.

1 Like
6

This could be a stretch as I haven’t tried to bind to dynamic import thus far, but Webpack Magic Comments could possibly be served by this.

1 Like
7

Isn’t the main use case for IDE intellisense when hovering over values imported from ReScript? We would love this – at the moment we’re using @ocaml.doc everywhere which works but is frankly just weird to see in ReScript files.

8

Not sure if this is related to output comments… So the way docs-on-hover works is by parsing our ReScript files for the ocaml.doc decorators via the editor-support and display that via the LSP.

Or are you referring to a method where you want the doc headers to be transferred to the JS as well, so that e.g. TS’ LSP will pick it up?

9

I was specifically referring to the latter, but I’ve also realised that I got a bit confused and actually the ocaml docs are not carried over to JS.

10

This would be great to have. I would love to be able to write JSDoc style comments for functions that are compiled over to JS/TS.

I’m working on a component library using ReScript at work that will be used by TypeScript react apps, and having TSDocs would be great.