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.
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?
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.
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.
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.
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?
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.
Hey, I’m curious if there’s any further progress here? It’s definitely a feature I’m interested in (for the same reason as mentioned above, writing a library in Rescript but I ship it as a ts/js package on npm, would like my comments propagated there)
How about killing two birds with one stone? The @@directive decorator takes any string literal and outputs it at the top of the generated JavaScript file. Instead, how about outputting it at the corresponding source position? Eg
// ...other stuff...
@@directive(`/** Sum two numbers */`)
let sum = (x, y) => x + y
It needs to be extended anyway, at least you cannot use it for “use server” yet, since that is usually not at the top of the file (mentioned in this issue).