{"action":"created","issue":{"url":"https://api.github.com/repos/esdoc/esdoc/issues/178","labels_url":"https://api.github.com/repos/esdoc/esdoc/issues/178/labels{/name}","comments_url":"https://api.github.com/repos/esdoc/esdoc/issues/178/comments","events_url":"https://api.github.com/repos/esdoc/esdoc/issues/178/events","html_url":"https://github.com/esdoc/esdoc/issues/178","id":118331513,"number":178,"title":"Support for destructuring in function parameters","user":{"login":"nodaguti","id":27622,"avatar_url":"https://avatars.githubusercontent.com/u/27622?v=3","gravatar_id":"","url":"https://api.github.com/users/nodaguti","html_url":"https://github.com/nodaguti","followers_url":"https://api.github.com/users/nodaguti/followers","following_url":"https://api.github.com/users/nodaguti/following{/other_user}","gists_url":"https://api.github.com/users/nodaguti/gists{/gist_id}","starred_url":"https://api.github.com/users/nodaguti/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nodaguti/subscriptions","organizations_url":"https://api.github.com/users/nodaguti/orgs","repos_url":"https://api.github.com/users/nodaguti/repos","events_url":"https://api.github.com/users/nodaguti/events{/privacy}","received_events_url":"https://api.github.com/users/nodaguti/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":2,"created_at":"2015-11-23T07:24:37Z","updated_at":"2015-11-23T08:10:41Z","closed_at":null,"body":"When using destructuring in function parameters, the current spec of **@param** is not enough.\r\nFor example, it's difficult to write a doc for the following function due to the mismatch between parameters and arguments.\r\n\r\n```javascript\r\nfunction foo ([a, b], {x: {y: c}}) {\r\n   return a + b + c;\r\n}\r\n\r\nfoo([1, 2], {x: {y: 3}});  // => 6\r\n```\r\n\r\nThis function requires an array as the first argument and an object as the second argument, and defines parameters `a`, `b` and `c` as number.\r\n\r\nHere is a quick try to write a doc for the above function with the current spec.\r\n\r\n```\r\n/**\r\n * @param {Array<number>} array desc.\r\n * @param {Object} obj\r\n * @param {Object} obj.x\r\n * @param {number} obj.x.y desc.\r\n * @return {number} desc.\r\n */\r\n```\r\n\r\nBut this docs has some problems such as:\r\n\r\n- The parameters `a`, `b`, `c` are not described.\r\n- Using dummy parameter names, `array` and `obj`, which are required due to the spec. (it says there must be the name of the documented parameter.)\r\n- This doesn't provide information about the fact that the only top 2 elements of an array will be used.\r\n\r\nFor this kind of ES6-specific problems, it seems that JSDoc has no plan to deal with (providing an workaround or building a new syntax) currently.\r\n\r\n- [JSDoc for destructurings · Issue #987 · jsdoc3/jsdoc](https://github.com/jsdoc3/jsdoc/issues/987)\r\n\r\nSo, I suggest introducing a few breaking changes into **@arg** and **@param**:\r\n\r\n- **@arg**: Stop treating it as an alias of **@param** and let @arg describe arguments.\r\n```\r\n@arg {type} reference_name description.\r\n```\r\n\r\n- **@param**: When using @param along with @arg, @param will indicate parameters referring @arg tags.\r\n```\r\n@param {type} parameter_name reference_expression description\r\n```\r\n\r\nAs an example, the doc for the above function will be:\r\n```\r\n/**\r\n * @arg {Array<number>} ref1 desc.\r\n * @arg {{x: {y: number}}} ref2 desc.\r\n * @param {number} a ref1[0] desc.\r\n * @param {number} b ref1[1] desc.\r\n * @param {number} c ref2.x.y desc.\r\n * @return {number} desc.\r\n */\r\n```\r\n\r\nWhat do you think?"},"comment":{"url":"https://api.github.com/repos/esdoc/esdoc/issues/comments/158873923","html_url":"https://github.com/esdoc/esdoc/issues/178#issuecomment-158873923","issue_url":"https://api.github.com/repos/esdoc/esdoc/issues/178","id":158873923,"user":{"login":"nodaguti","id":27622,"avatar_url":"https://avatars.githubusercontent.com/u/27622?v=3","gravatar_id":"","url":"https://api.github.com/users/nodaguti","html_url":"https://github.com/nodaguti","followers_url":"https://api.github.com/users/nodaguti/followers","following_url":"https://api.github.com/users/nodaguti/following{/other_user}","gists_url":"https://api.github.com/users/nodaguti/gists{/gist_id}","starred_url":"https://api.github.com/users/nodaguti/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nodaguti/subscriptions","organizations_url":"https://api.github.com/users/nodaguti/orgs","repos_url":"https://api.github.com/users/nodaguti/repos","events_url":"https://api.github.com/users/nodaguti/events{/privacy}","received_events_url":"https://api.github.com/users/nodaguti/received_events","type":"User","site_admin":false},"created_at":"2015-11-23T08:10:41Z","updated_at":"2015-11-23T08:10:41Z","body":"Array destructuring in function parameters is somewhat broken?\r\n\r\n```\r\nwarning: signature mismatch: Foo#foo src/test.js#2\r\n1| /**\r\n2|  * @param {Array<number>} coord hoge\r\n3|  * @param {{x: {y: number}}} opts fuga\r\n4|  * @return {number} desc.\r\n5|  */\r\n6| foo([a, b], {x: {y: c}}) {\r\n```"}}