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.