{"issue":{"title":"YARD swallows options when using *args","user":{"login":"joliss","id":524783,"url":"https://api.github.com/users/joliss","avatar_url":"https://secure.gravatar.com/avatar/4d6f74711436cfe252bf4fc8f3cf4971?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-140.png","gravatar_id":"4d6f74711436cfe252bf4fc8f3cf4971"},"created_at":"2011-12-28T15:53:16Z","milestone":null,"labels":[],"state":"closed","updated_at":"2011-12-28T21:00:50Z","id":2672263,"closed_at":"2011-12-28T20:32:27Z","html_url":"https://github.com/lsegal/yard/issues/439","pull_request":{"patch_url":null,"html_url":null,"diff_url":null},"body":"If you document options like so:\r\n\r\n      # @option options [String] :subject The subject\r\n      def method(options)\r\n      end\r\n\r\nThey show up correctly in the YARD output:\r\n\r\n> Parameters:\r\n> * options (Hash) — a customizable set of options\r\n> Options Hash (options):\r\n> * :subject (String) — The subject\r\n\r\nBut if you don't have the `options` parameter in the method signature -- commonly, if you have an `*args` parameter -- the option documentation gets dropped:\r\n\r\n      # @option options [String] :subject The subject\r\n      def method(*args)\r\n      end\r\n\r\n> Parameters:\r\n> options (Hash) — a customizable set of options\r\n\r\n(This is being a real-life problem for Capybara's API documentation, since Capybara uses the `*args` pass-through technique extensively.)","number":439,"url":"https://api.github.com/repos/lsegal/yard/issues/439","comments":4,"assignee":null},"comment":{"user":{"login":"joliss","id":524783,"url":"https://api.github.com/users/joliss","avatar_url":"https://secure.gravatar.com/avatar/4d6f74711436cfe252bf4fc8f3cf4971?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-140.png","gravatar_id":"4d6f74711436cfe252bf4fc8f3cf4971"},"created_at":"2011-12-28T21:00:50Z","updated_at":"2011-12-28T21:00:50Z","id":3295065,"body":"Interesting, thanks for the pointer! `@overload` should solve the problem for now.\r\n\r\nLet me try to explain though why I find YARD's current behavior suboptimal:\r\n\r\n* Documentation gets dropped silently, so developers don't realize things are going wrong. For example, I don't think anybody noticed until now that the `@option` tags added here in July 2010 https://github.com/jnicklas/capybara/commit/cbfbb32228a6 never showed up in the API docs.\r\n\r\n* When there's an `*args` splat, I think it's reasonable to expect that any parameters in the documentation are in fact correct.\r\n\r\nSo I guess I just don't feel that this sanity check is helpful at all.\r\n\r\nAnyways, not to bicker -- it's your call, just thought I'd explain why I'm unhappy about this.","url":"https://api.github.com/repos/lsegal/yard/issues/comments/3295065"},"action":"created"}