Hi all
Where can I find a good explanation about annotations for example @bs.val, @bs.module, @bs.send, etc?
I’ve found https://bucklescript.github.io/bucklescript/Manual.html#_binding_to_a_value_from_a_module_code_bs_module_code
But I am not sure, if it is up-to-date.
Thanks
@bs.module https://bucklescript.github.io/docs/en/import-export.html
@bs.val https://bucklescript.github.io/docs/en/bind-to-global-values.html
@bs.send https://bucklescript.github.io/docs/en/function.html#object-method
Sorry for being naive about OCaml terminology. But what are these special looking annotations in OCaml world? So far, I have seen @bs.val, @bs.module, @bs.send, @bs.send, @bs.meth, [@bs.deriving abstract], etc.
What are these entities called? Are they similar to decorators that we see in other languages? Is that syntax specific to BuckleScript or general compiler directives for OCaml or some sort of native language construct? I could not Google it as I do not really know what I should be looking for.
Any link explaining this concept would be great.
Hi, in general these annotations are called extension points and they tell the compiler to transform the parsed syntax tree in a particular way. So they are pretty similar to macros, in a limited way. Here’s a good write-up: https://victor.darvariu.me/jekyll/update/2018/06/19/ppx-tutorial.html
To expand on the original question further, I am beginning to see library authors consider using these annotations / extension points in the core APIs of their tools, eg:
Given the API consumers are seemingly going to need to understand how these constructs affect their code, it seems it deserves a solid explanation in the core ReasonML docs. I understand that BuckleScript uses annotations itself, but those docs don’t actually explain to users how the annotation construct works, just how BuckleScript’s specific annotations work with FFI.
The link to the PPX tutorial here is a fine resource, but largely undiscoverable. And the fact that PPX is only referenced in the ReasonML docs as a warning to lib authors about their use makings things harder for newcomers, only further adds to the argument that they should be explained somewhere within the ReasonML docs, even if it was a new “advanced” section.
TLDR; given annotations are now to be used by consumers of popular libs, the docs should explain annotations as a construct to be discoverable.
I also found it quite confusing at a newcomer that I couldn’t find a reference listing all the available annotations.
Perhaps we could link to the available annotations in the source?
The new, community-run, docs have a page listing all of the [@bs.*] annotations: https://reasonml.org/docs/reason-compiler/latest/decorators