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.

11

Bumping this old thread to keep it alive.

I’m currently working on a component library using ReScript and storybook has this nice feature that allows it to show documentation for props if you add comments to the TS types.

type Prop = {
  /** A person's name **/
  name: string
}

And then when you look at the storybook story and the compments props you will see the description for the prop.

We also use a lot of TS doc in other parts of our code and it would be nice to have a way to preserve comments in the compiled JS.

12

ts-belt uses a very neat utility PPX for this use case:

%comment("sum two numbers")
let sum = (x, y) => x + y

The PPX is actually pretty small (~30 LOCs) [source]. So if you really need doc comments, it might be worth bringing this PPX to your project.

2 Likes
13

Oh nice! I’ll look into that.

14

Ooo this is really valuable, is this something that can be published to npm? I’m not familiar with PPX or dune, but this is something I can really use

3 Likes