{"action":"created","issue":{"url":"https://api.github.com/repos/purescript/purescript/issues/1081","labels_url":"https://api.github.com/repos/purescript/purescript/issues/1081/labels{/name}","comments_url":"https://api.github.com/repos/purescript/purescript/issues/1081/comments","events_url":"https://api.github.com/repos/purescript/purescript/issues/1081/events","html_url":"https://github.com/purescript/purescript/issues/1081","id":70976756,"number":1081,"title":"Improving doc-comment syntax","user":{"login":"hdgarrood","id":1270186,"avatar_url":"https://avatars.githubusercontent.com/u/1270186?v=3","gravatar_id":"","url":"https://api.github.com/users/hdgarrood","html_url":"https://github.com/hdgarrood","followers_url":"https://api.github.com/users/hdgarrood/followers","following_url":"https://api.github.com/users/hdgarrood/following{/other_user}","gists_url":"https://api.github.com/users/hdgarrood/gists{/gist_id}","starred_url":"https://api.github.com/users/hdgarrood/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/hdgarrood/subscriptions","organizations_url":"https://api.github.com/users/hdgarrood/orgs","repos_url":"https://api.github.com/users/hdgarrood/repos","events_url":"https://api.github.com/users/hdgarrood/events{/privacy}","received_events_url":"https://api.github.com/users/hdgarrood/received_events","type":"User","site_admin":false},"labels":[],"state":"closed","locked":false,"assignee":null,"milestone":null,"comments":5,"created_at":"2015-04-25T22:32:28Z","updated_at":"2015-08-08T01:44:08Z","closed_at":"2015-08-08T01:44:08Z","body":"I have a couple of minor gripes with the current doc-comment syntax:\r\n\r\n1. Mixing docs with non-docs is too hard\r\n2. Putting a pipe at the start of every line is too fiddly. This is particularly bad for non-{emacs,vim} users.\r\n\r\nAn example of the first problem - I want the documentation comments here to come through to the rendered psc-docs version, but not the TODO:\r\n\r\n```purescript\r\n-- | O(log(min(i,n-i))). Adjust the element at the specified index by\r\n-- | applying the given function to it. If the index is out of range, the\r\n-- | sequence is returned unchanged.\r\n-- TODO: Investigate whether this can be optimized.\r\nadjust :: forall a. (a -> a) -> Number -> Seq a -> Seq a\r\nadjust f i xs = if inBounds xs i then unsafeAdjust f i xs else xs\r\n```\r\n\r\nThis will currently result in no documentation appearing at all, because the code currently checks that every line starts with a pipe, and ignores the whole lot if the check fails.\r\n\r\nI think we can solve both of these issues in one hit, while mostly maintaining backwards compatibility, by using block comments (since nobody seems to be using them for docs at the moment).\r\n\r\n1. In the case where a declaration is accompanied by a documentation block comment, it makes sense to assume that it contains all of the documentation - all other comments can probably be ignored.\r\n2. Relax the requirement for block comments that every line start with a pipe. Instead, just ensure that the whole comment starts with a pipe.\r\n\r\nExample:\r\n\r\n```purescript\r\n{-| O(log(min(i,n-i))). Adjust the element at the specified index by applying\r\nthe given function to it. If the index is out of range, the sequence is\r\nreturned unchanged.\r\n-}\r\n-- TODO: Investigate whether this can be optimized.\r\nadjust :: forall a. (a -> a) -> Number -> Seq a -> Seq a\r\nadjust f i xs = if inBounds xs i then unsafeAdjust f i xs else xs\r\n```\r\n\r\nIf we standardise on block comments (across core libraries, purescript book, etc) then other people will probably start writing code in the same way, which I think would mean less pain for everyone.\r\n\r\nIf there's agreement I will probably send a PR soon. This would be a tiny change, 20 lines or so maximum."},"comment":{"url":"https://api.github.com/repos/purescript/purescript/issues/comments/128880472","html_url":"https://github.com/purescript/purescript/issues/1081#issuecomment-128880472","issue_url":"https://api.github.com/repos/purescript/purescript/issues/1081","id":128880472,"user":{"login":"paf31","id":630306,"avatar_url":"https://avatars.githubusercontent.com/u/630306?v=3","gravatar_id":"","url":"https://api.github.com/users/paf31","html_url":"https://github.com/paf31","followers_url":"https://api.github.com/users/paf31/followers","following_url":"https://api.github.com/users/paf31/following{/other_user}","gists_url":"https://api.github.com/users/paf31/gists{/gist_id}","starred_url":"https://api.github.com/users/paf31/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/paf31/subscriptions","organizations_url":"https://api.github.com/users/paf31/orgs","repos_url":"https://api.github.com/users/paf31/repos","events_url":"https://api.github.com/users/paf31/events{/privacy}","received_events_url":"https://api.github.com/users/paf31/received_events","type":"User","site_admin":false},"created_at":"2015-08-08T01:44:08Z","updated_at":"2015-08-08T01:44:08Z","body":"I'm going to vote for the aligned `|`s too, since I think it makes it easier to format non-trivial Markdown."}}