{"action":"created","issue":{"url":"https://api.github.com/repos/JuliaLang/julia/issues/12000","labels_url":"https://api.github.com/repos/JuliaLang/julia/issues/12000/labels{/name}","comments_url":"https://api.github.com/repos/JuliaLang/julia/issues/12000/comments","events_url":"https://api.github.com/repos/JuliaLang/julia/issues/12000/events","html_url":"https://github.com/JuliaLang/julia/pull/12000","id":92796096,"number":12000,"title":"Better support for documenting expressions with macros","user":{"login":"yuyichao","id":712232,"avatar_url":"https://avatars.githubusercontent.com/u/712232?v=3","gravatar_id":"","url":"https://api.github.com/users/yuyichao","html_url":"https://github.com/yuyichao","followers_url":"https://api.github.com/users/yuyichao/followers","following_url":"https://api.github.com/users/yuyichao/following{/other_user}","gists_url":"https://api.github.com/users/yuyichao/gists{/gist_id}","starred_url":"https://api.github.com/users/yuyichao/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/yuyichao/subscriptions","organizations_url":"https://api.github.com/users/yuyichao/orgs","repos_url":"https://api.github.com/users/yuyichao/repos","events_url":"https://api.github.com/users/yuyichao/events{/privacy}","received_events_url":"https://api.github.com/users/yuyichao/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/JuliaLang/julia/labels/docsystem","name":"docsystem","color":"d4c5f9"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":11,"created_at":"2015-07-03T05:32:08Z","updated_at":"2015-07-03T19:33:48Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/JuliaLang/julia/pulls/12000","html_url":"https://github.com/JuliaLang/julia/pull/12000","diff_url":"https://github.com/JuliaLang/julia/pull/12000.diff","patch_url":"https://github.com/JuliaLang/julia/pull/12000.patch"},"body":"Fix #11993 (not sure if this is the best way though)\r\n\r\n* Update:\r\n\r\n    See below for the current behavior https://github.com/JuliaLang/julia/pull/12000#issuecomment-118404697 and examples of it https://github.com/JuliaLang/julia/pull/12000#issuecomment-118410489\r\n\r\n    It still uses `macroexpand` in a `macro`.\r\n\r\nOriginal post:\r\n\r\n1. Disallow documenting macro with\r\n\r\n    ```\r\n    \"<doc>\"\r\n    @macro\r\n    ```\r\n\r\n    syntax since it can be ambiguous with expanding and using the macro (which might have side effects)\r\n\r\n2. Expand the macro if the expression to be documented is a macro call in order to document the correct object.\r\n\r\nIssues\r\n\r\n1. This is calling `macroexpand` in a macro. Not sure if this is the best thing to do but I couldn't come up with a better way to do what I want.\r\n\r\n2. ~~Both `\"\" @m` and~~ `\"\"<\\n>@m` ~~are~~ is parsed as\r\n\r\n    ```julia\r\n    quote\r\n        \"\"\r\n        @id\r\n    end\r\n    ```\r\n\r\n    ~~The former should probably be reallowed,~~(edit: fixed) ~~the latter~~ this should probably not have the `block` (although I couldn't figure out if I can reset the input stream)\r\n"},"comment":{"url":"https://api.github.com/repos/JuliaLang/julia/issues/comments/118411713","html_url":"https://github.com/JuliaLang/julia/pull/12000#issuecomment-118411713","issue_url":"https://api.github.com/repos/JuliaLang/julia/issues/12000","id":118411713,"user":{"login":"yuyichao","id":712232,"avatar_url":"https://avatars.githubusercontent.com/u/712232?v=3","gravatar_id":"","url":"https://api.github.com/users/yuyichao","html_url":"https://github.com/yuyichao","followers_url":"https://api.github.com/users/yuyichao/followers","following_url":"https://api.github.com/users/yuyichao/following{/other_user}","gists_url":"https://api.github.com/users/yuyichao/gists{/gist_id}","starred_url":"https://api.github.com/users/yuyichao/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/yuyichao/subscriptions","organizations_url":"https://api.github.com/users/yuyichao/orgs","repos_url":"https://api.github.com/users/yuyichao/repos","events_url":"https://api.github.com/users/yuyichao/events{/privacy}","received_events_url":"https://api.github.com/users/yuyichao/received_events","type":"User","site_admin":false},"created_at":"2015-07-03T19:33:48Z","updated_at":"2015-07-03T19:33:48Z","body":"> (Sorry for being lazy and not just trying it out!)\r\n\r\nNP. I don't always like to wait for ~10min to compile someone else's PR either.... :P \r\n\r\n> would this work with this PR? \r\n\r\nNot directly and not on current master either because\r\n\r\n1. A normal macro call cannot use newline to separate arguments.\r\n2. The return value is not the type.\r\n\r\nThis works.\r\n```julia\r\njulia> macro mkT(f)\r\n       quote\r\n       immutable $f end\r\n       g() = 5\r\n       $f\r\n       end\r\n       end\r\n\r\njulia> @doc \"\"\"\r\n       My T1\r\n       \"\"\" @mkT T1\r\nT1\r\n\r\njulia> \"\"\"\r\n       My T2\r\n       \"\"\"\r\n       @mkT T2\r\nT2\r\n\r\nhelp?> T1\r\nsearch: T1 Int16 int16 Int128 rot180 int128 UInt16 uint16 Uint16 UInt128 uint128\r\n\r\n  My T1\r\n\r\nhelp?> T2\r\nsearch: T2 hist2d hist2d! Int32 int32 Int128 int128 UInt32 uint32 Uint32 UInt128\r\n\r\n  My T2\r\n```\r\n\r\nThe expansion of the macro is not a single type definition so `@doc` or `@s_doc` will not recognize the structure. However, as long as the expression evaluates to the type, it can document the object with no problem.\r\n\r\nP.S. The only exception to the above rules are macro definition (which doesn't return anything) and function definition (which returns the function and not the method, a behavior that is useful in many cases). In these cases, you would have to let `@doc` see the original syntax in order to document the correct stuff.\r\n"}}