{"action":"created","issue":{"url":"https://api.github.com/repos/ocaml/ocaml/issues/380","labels_url":"https://api.github.com/repos/ocaml/ocaml/issues/380/labels{/name}","comments_url":"https://api.github.com/repos/ocaml/ocaml/issues/380/comments","events_url":"https://api.github.com/repos/ocaml/ocaml/issues/380/events","html_url":"https://github.com/ocaml/ocaml/pull/380","id":124098715,"number":380,"title":"MPR#7109: documentation and ocamldoc, fix bigarray documentation","user":{"login":"Octachron","id":7689388,"avatar_url":"https://avatars.githubusercontent.com/u/7689388?v=3","gravatar_id":"","url":"https://api.github.com/users/Octachron","html_url":"https://github.com/Octachron","followers_url":"https://api.github.com/users/Octachron/followers","following_url":"https://api.github.com/users/Octachron/following{/other_user}","gists_url":"https://api.github.com/users/Octachron/gists{/gist_id}","starred_url":"https://api.github.com/users/Octachron/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Octachron/subscriptions","organizations_url":"https://api.github.com/users/Octachron/orgs","repos_url":"https://api.github.com/users/Octachron/repos","events_url":"https://api.github.com/users/Octachron/events{/privacy}","received_events_url":"https://api.github.com/users/Octachron/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":2,"created_at":"2015-12-28T17:55:18Z","updated_at":"2015-12-28T22:08:29Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/ocaml/ocaml/pulls/380","html_url":"https://github.com/ocaml/ocaml/pull/380","diff_url":"https://github.com/ocaml/ocaml/pull/380.diff","patch_url":"https://github.com/ocaml/ocaml/pull/380.patch"},"body":"This pull request fixes the documentation layout in `otherlibs/bigarray.mli`.\r\n\r\nSome documentation comments in `bigarray.mli` were wrongly attached to the last constructor of their related type definitions when they should have be attached to the type definition.\r\n\r\nTo fix this attachment problem, the two possible solutions are either to detach completely the concerned documentation comments or to add an empty documentation just after the last constructor.\r\n\r\nThe last solution gives the expected attachment and seems better on the long term; however most documentation generators tends to print these empty documentation comments as `(* *)`. \r\n\r\nSince these empty constructor comments do not really convey any information (except maybe \"ocamldoc implementation is quite complex\"), this pull request proposes to simply erase such empty comments in ocamldoc itself.\r\n\r\nWith these two commits, the bigarray documentation should be restored to its correct state."},"comment":{"url":"https://api.github.com/repos/ocaml/ocaml/issues/comments/167666737","html_url":"https://github.com/ocaml/ocaml/pull/380#issuecomment-167666737","issue_url":"https://api.github.com/repos/ocaml/ocaml/issues/380","id":167666737,"user":{"login":"gasche","id":426238,"avatar_url":"https://avatars.githubusercontent.com/u/426238?v=3","gravatar_id":"","url":"https://api.github.com/users/gasche","html_url":"https://github.com/gasche","followers_url":"https://api.github.com/users/gasche/followers","following_url":"https://api.github.com/users/gasche/following{/other_user}","gists_url":"https://api.github.com/users/gasche/gists{/gist_id}","starred_url":"https://api.github.com/users/gasche/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gasche/subscriptions","organizations_url":"https://api.github.com/users/gasche/orgs","repos_url":"https://api.github.com/users/gasche/repos","events_url":"https://api.github.com/users/gasche/events{/privacy}","received_events_url":"https://api.github.com/users/gasche/received_events","type":"User","site_admin":false},"created_at":"2015-12-28T22:08:29Z","updated_at":"2015-12-28T22:08:29Z","body":"One solution (but I hope there are better ones) would be to have ocamldoc warn when no constructors are documented but the last one. This is quite likely to actually be this case that we are hitting, and otherwise people can just add an empty comment on another constructor. Of course that does not work on one-constructor datatypes."}}