{"action":"created","issue":{"url":"https://api.github.com/repos/alainfrisch/gen_js_api/issues/29","labels_url":"https://api.github.com/repos/alainfrisch/gen_js_api/issues/29/labels{/name}","comments_url":"https://api.github.com/repos/alainfrisch/gen_js_api/issues/29/comments","events_url":"https://api.github.com/repos/alainfrisch/gen_js_api/issues/29/events","html_url":"https://github.com/alainfrisch/gen_js_api/issues/29","id":71338112,"number":29,"title":"Documentation integration","user":{"login":"dbuenzli","id":485596,"avatar_url":"https://avatars.githubusercontent.com/u/485596?v=3","gravatar_id":"","url":"https://api.github.com/users/dbuenzli","html_url":"https://github.com/dbuenzli","followers_url":"https://api.github.com/users/dbuenzli/followers","following_url":"https://api.github.com/users/dbuenzli/following{/other_user}","gists_url":"https://api.github.com/users/dbuenzli/gists{/gist_id}","starred_url":"https://api.github.com/users/dbuenzli/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/dbuenzli/subscriptions","organizations_url":"https://api.github.com/users/dbuenzli/orgs","repos_url":"https://api.github.com/users/dbuenzli/repos","events_url":"https://api.github.com/users/dbuenzli/events{/privacy}","received_events_url":"https://api.github.com/users/dbuenzli/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":1,"created_at":"2015-04-27T16:36:06Z","updated_at":"2015-04-27T16:40:18Z","closed_at":null,"body":"Having seen Seb's recent JS's `Date` bindings, they look great. \r\n\r\nHowever something I feel is missing is a way of generating links to documentation so that `ocamldoc`'d `mli`s have direct links to the documentation of the bound function (see e.g. the documentation of functions in [tgls](http://erratique.ch/software/tgls/doc/Tgl4.Gl.html#funs), automatically generated, or [tsdl](http://erratique.ch/software/tsdl/doc/Tsdl.Sdl.html#basics), 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.\r\n\r\nMost 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 `mli`s. 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 `mli`s and provide support for automatically generating doc strings.\r\n\r\nThe 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date).\r\n \r\n\r\n\r\n\r\n"},"comment":{"url":"https://api.github.com/repos/alainfrisch/gen_js_api/issues/comments/96734301","html_url":"https://github.com/alainfrisch/gen_js_api/issues/29#issuecomment-96734301","issue_url":"https://api.github.com/repos/alainfrisch/gen_js_api/issues/29","id":96734301,"user":{"login":"alainfrisch","id":3305274,"avatar_url":"https://avatars.githubusercontent.com/u/3305274?v=3","gravatar_id":"","url":"https://api.github.com/users/alainfrisch","html_url":"https://github.com/alainfrisch","followers_url":"https://api.github.com/users/alainfrisch/followers","following_url":"https://api.github.com/users/alainfrisch/following{/other_user}","gists_url":"https://api.github.com/users/alainfrisch/gists{/gist_id}","starred_url":"https://api.github.com/users/alainfrisch/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/alainfrisch/subscriptions","organizations_url":"https://api.github.com/users/alainfrisch/orgs","repos_url":"https://api.github.com/users/alainfrisch/repos","events_url":"https://api.github.com/users/alainfrisch/events{/privacy}","received_events_url":"https://api.github.com/users/alainfrisch/received_events","type":"User","site_admin":false},"created_at":"2015-04-27T16:40:18Z","updated_at":"2015-04-27T16:40:18Z","body":"This is a very good point.\r\n\r\nIn 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."}}