Documentation integration

[dbuenzli]

Having seen Seb's recent JS's Date bindings, they look great.

However something I feel is missing is a way of generating links to documentation so that ocamldoc'd mlis have direct links to the documentation of the bound function (see e.g. the documentation of functions in tgls, automatically generated, or tsdl, manually done with a lot of query-replace-regexp). These are small touches but they have a huge productivity impact when you are working with the binding.

Most of the time it is sufficient to be able to define an URI pattern where a variable is substituted by the bound method name (and the ability to override in case of exceptions). Now one of the problem is that you don't generate the mlis. If your eventual goal is to generate mli's from other descriptions then this could actually be done at that time, otherwise you might consider generating mli's aswell from the annotated mlis and provide support for automatically generating doc strings.

The other problem is to find a good and reliable source of documentation for the browser APIs, directly linking on the standards may be a little bit dry. I tend to use mozilla's developer documentation which has links to the standards and information about browser support. See e.g. the Date documentation.

[alainfrisch]

This is a very good point.

In the medium term (once codoc take over ocamldoc), documentation comments will be extract from comments, and one could very well use gen_js_api as a ppx mapper on .mli interfaces that will insert extra docstrings obtained from generic heuristics.