{"action":"created","issue":{"url":"https://api.github.com/repos/jleyba/js-dossier/issues/30","labels_url":"https://api.github.com/repos/jleyba/js-dossier/issues/30/labels{/name}","comments_url":"https://api.github.com/repos/jleyba/js-dossier/issues/30/comments","events_url":"https://api.github.com/repos/jleyba/js-dossier/issues/30/events","html_url":"https://github.com/jleyba/js-dossier/issues/30","id":96118348,"number":30,"title":"abstract method shows wrong parameter info","user":{"login":"myphysicslab","id":4060786,"avatar_url":"https://avatars.githubusercontent.com/u/4060786?v=3","gravatar_id":"","url":"https://api.github.com/users/myphysicslab","html_url":"https://github.com/myphysicslab","followers_url":"https://api.github.com/users/myphysicslab/followers","following_url":"https://api.github.com/users/myphysicslab/following{/other_user}","gists_url":"https://api.github.com/users/myphysicslab/gists{/gist_id}","starred_url":"https://api.github.com/users/myphysicslab/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/myphysicslab/subscriptions","organizations_url":"https://api.github.com/users/myphysicslab/orgs","repos_url":"https://api.github.com/users/myphysicslab/repos","events_url":"https://api.github.com/users/myphysicslab/events{/privacy}","received_events_url":"https://api.github.com/users/myphysicslab/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/jleyba/js-dossier/labels/bug","name":"bug","color":"fc2929"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":1,"created_at":"2015-07-20T17:41:54Z","updated_at":"2015-09-03T04:03:29Z","closed_at":null,"body":"Abstract methods show up like this in docs:\r\n\r\n```\r\naddPath(arg0)\r\n\r\nSpecified by: myphysicslab.lab.engine2D.Edge\r\n\r\nParameters\r\narg0...?\r\n```\r\n\r\ninstead of showing the correct parameter information from the Edge interface:\r\n\r\n```\r\naddPath(context)\r\n\r\nAdd this Edge to the currently open path of the JavaScript canvas context. The Edge should be rendered in local body coordinates.\r\n\r\nParameters\r\ncontextCanvasRenderingContext2D\r\nthe JavaScript canvas context to draw this object into\r\n\r\n```\r\n\r\nHere is some of the code involved:\r\n\r\n```javascript\r\n/** \r\n* @interface\r\n*/\r\nmyphysicslab.lab.engine2D.Edge = function() {};\r\n\r\n/** Add this {Edge} to the currently open path of the JavaScript canvas context.\r\nThe {Edge} should be rendered in local body coordinates.\r\n@method\r\n@param {!CanvasRenderingContext2D} context the JavaScript canvas context to draw this\r\nobject into\r\n*/\r\nEdge.prototype.addPath\r\n\r\n/**\r\n* @param {!myphysicslab.lab.engine2D.Polygon} body\r\n* @param {!myphysicslab.lab.engine2D.Vertex} vertex1 the previous vertex, in body\r\n  coords; matches the next (second) vertex of the previous edge\r\n* @param {!myphysicslab.lab.engine2D.Vertex} vertex2 the next vertex, in body coords\r\n* @constructor\r\n* @struct\r\n* @implements {myphysicslab.lab.engine2D.Edge}\r\n*/\r\nmyphysicslab.lab.engine2D.AbstractEdge = function(body, vertex1, vertex2) {\r\n  // code omitted...\r\n};\r\n\r\n/** @inheritDoc */\r\nAbstractEdge.prototype.addPath = goog.abstractMethod;\r\n```\r\n\r\n\r\n\r\n"},"comment":{"url":"https://api.github.com/repos/jleyba/js-dossier/issues/comments/137324062","html_url":"https://github.com/jleyba/js-dossier/issues/30#issuecomment-137324062","issue_url":"https://api.github.com/repos/jleyba/js-dossier/issues/30","id":137324062,"user":{"login":"jleyba","id":254985,"avatar_url":"https://avatars.githubusercontent.com/u/254985?v=3","gravatar_id":"","url":"https://api.github.com/users/jleyba","html_url":"https://github.com/jleyba","followers_url":"https://api.github.com/users/jleyba/followers","following_url":"https://api.github.com/users/jleyba/following{/other_user}","gists_url":"https://api.github.com/users/jleyba/gists{/gist_id}","starred_url":"https://api.github.com/users/jleyba/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jleyba/subscriptions","organizations_url":"https://api.github.com/users/jleyba/orgs","repos_url":"https://api.github.com/users/jleyba/repos","events_url":"https://api.github.com/users/jleyba/events{/privacy}","received_events_url":"https://api.github.com/users/jleyba/received_events","type":"User","site_admin":false},"created_at":"2015-09-03T04:03:29Z","updated_at":"2015-09-03T04:03:29Z","body":"I've run into some ambiguity over when to use the documentation from a super type.  Suppose we have:\r\n\r\n```\r\n/** @constructor */\r\nvar Greeter = function() {};\r\n\r\n/**\r\n * Generates a greeting.\r\n * @param {string} name Name of the person to greet.\r\n * @return {string} The greeting.\r\n */\r\nGreeter.prototype.greet = goog.abstractMethod;\r\n\r\n/**\r\n * @constructor\r\n * @extends {Greeter}\r\n */\r\nvar CustomGreeter = function() {};\r\n\r\n/**\r\n * Generates a custom greeting.\r\n * @override\r\n */\r\nCustomGreeter.prototype.greet = function() {};\r\n```\r\n\r\nIf `CustomGreeter.prototype.greet` simply had `/** @override */`, we can easily grab the docs from the super type. But above, there is a block description. Do we\r\n\r\n1. Use the block comment and inherit the documentation for the annotations. The docs will also include an \"Overrides: Greeter#greet\" link.\r\n2. Use the block comment, but leave everything else empty with an \"Overrides: Greeter#greet\" link.\r\n\r\nWhat if the comment overrides the documentation just for the `@param`:\r\n```\r\n/** \r\n * @param {string} name The name of a funny person.\r\n * @override\r\n */\r\nCustomGreeter.prototype.greet = function() {};\r\n```\r\n\r\nHere, do we use the `@param` and inherit everything else, or just include the \"Overrides...\" link?"}}