{"action":"created","issue":{"url":"https://api.github.com/repos/JuliaLang/julia/issues/8966","labels_url":"https://api.github.com/repos/JuliaLang/julia/issues/8966/labels{/name}","comments_url":"https://api.github.com/repos/JuliaLang/julia/issues/8966/comments","events_url":"https://api.github.com/repos/JuliaLang/julia/issues/8966/events","html_url":"https://github.com/JuliaLang/julia/issues/8966","id":48288166,"number":8966,"title":"formatting conventions for function documentation","user":{"login":"stevengj","id":2913679,"avatar_url":"https://avatars.githubusercontent.com/u/2913679?v=3","gravatar_id":"","url":"https://api.github.com/users/stevengj","html_url":"https://github.com/stevengj","followers_url":"https://api.github.com/users/stevengj/followers","following_url":"https://api.github.com/users/stevengj/following{/other_user}","gists_url":"https://api.github.com/users/stevengj/gists{/gist_id}","starred_url":"https://api.github.com/users/stevengj/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/stevengj/subscriptions","organizations_url":"https://api.github.com/users/stevengj/orgs","repos_url":"https://api.github.com/users/stevengj/repos","events_url":"https://api.github.com/users/stevengj/events{/privacy}","received_events_url":"https://api.github.com/users/stevengj/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/JuliaLang/julia/labels/decision","name":"decision","color":"F08000"},{"url":"https://api.github.com/repos/JuliaLang/julia/labels/doc","name":"doc","color":"02d7e1"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":18,"created_at":"2014-11-10T17:08:49Z","updated_at":"2015-01-20T03:53:15Z","closed_at":null,"body":"Right now, the `@doc` help suggests;\r\n```\r\n  @doc \"\"\"\r\n    # The Foo Function\r\n    `foo(x)`: Foo the living hell out of `x`.\r\n  \"\"\" ->\r\n  function foo() ...\r\n```\r\n\r\nIn method documentation, wouldn't it be much more satisfactory () for the `help` command to automatically prepend the signature for `foo` before the documentation output as needed?\r\n\r\nIn generic-function documentation (e.g. documentation for `sum` in all its forms), obviously this is not possible (since there will in general be multiple possible signatures).   However, we should establish some convention for what the documentation should look like."},"comment":{"url":"https://api.github.com/repos/JuliaLang/julia/issues/comments/70600813","html_url":"https://github.com/JuliaLang/julia/issues/8966#issuecomment-70600813","issue_url":"https://api.github.com/repos/JuliaLang/julia/issues/8966","id":70600813,"user":{"login":"hayd","id":1931852,"avatar_url":"https://avatars.githubusercontent.com/u/1931852?v=3","gravatar_id":"","url":"https://api.github.com/users/hayd","html_url":"https://github.com/hayd","followers_url":"https://api.github.com/users/hayd/followers","following_url":"https://api.github.com/users/hayd/following{/other_user}","gists_url":"https://api.github.com/users/hayd/gists{/gist_id}","starred_url":"https://api.github.com/users/hayd/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/hayd/subscriptions","organizations_url":"https://api.github.com/users/hayd/orgs","repos_url":"https://api.github.com/users/hayd/repos","events_url":"https://api.github.com/users/hayd/events{/privacy}","received_events_url":"https://api.github.com/users/hayd/received_events","type":"User","site_admin":false},"created_at":"2015-01-20T03:53:15Z","updated_at":"2015-01-20T03:53:15Z","body":"I was having a play trying to put together a MetaDoc type a'la @stevengj in https://github.com/JuliaLang/julia/issues/8514#issuecomment-57331690 and https://github.com/JuliaLang/julia/pull/8588#issuecomment-60244983, it doesn't seem to play well with `@doc` I think this is since you can't override mdify (but no doubt I'm missing something)....\r\n\r\nAnyways a gist is here: https://gist.github.com/hayd/bdddb51dc7df89b9a24e\r\n\r\n*Thinking about it may be that you could just extract sections from the text i.e. lower @jiahao's docstrings into MetaDoc... (kind of [docopt](http://docopt.org/)-style).*\r\n\r\nThere's some discussion about Returns section (and how you could use this) in PR to prepend signature info to the help message: https://github.com/JuliaLang/julia/pull/9838."}}