{"action":"created","issue":{"url":"https://api.github.com/repos/electron/electron/issues/7337","repository_url":"https://api.github.com/repos/electron/electron","labels_url":"https://api.github.com/repos/electron/electron/issues/7337/labels{/name}","comments_url":"https://api.github.com/repos/electron/electron/issues/7337/comments","events_url":"https://api.github.com/repos/electron/electron/issues/7337/events","html_url":"https://github.com/electron/electron/issues/7337","id":179020694,"number":7337,"title":"The docs and the style guide should contain the return value of methods when relevant","user":{"login":"MarshallOfSound","id":6634592,"avatar_url":"https://avatars.githubusercontent.com/u/6634592?v=3","gravatar_id":"","url":"https://api.github.com/users/MarshallOfSound","html_url":"https://github.com/MarshallOfSound","followers_url":"https://api.github.com/users/MarshallOfSound/followers","following_url":"https://api.github.com/users/MarshallOfSound/following{/other_user}","gists_url":"https://api.github.com/users/MarshallOfSound/gists{/gist_id}","starred_url":"https://api.github.com/users/MarshallOfSound/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/MarshallOfSound/subscriptions","organizations_url":"https://api.github.com/users/MarshallOfSound/orgs","repos_url":"https://api.github.com/users/MarshallOfSound/repos","events_url":"https://api.github.com/users/MarshallOfSound/events{/privacy}","received_events_url":"https://api.github.com/users/MarshallOfSound/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/electron/electron/labels/documentation","name":"documentation","color":"eb6420"}],"state":"open","locked":false,"assignee":{"login":"MarshallOfSound","id":6634592,"avatar_url":"https://avatars.githubusercontent.com/u/6634592?v=3","gravatar_id":"","url":"https://api.github.com/users/MarshallOfSound","html_url":"https://github.com/MarshallOfSound","followers_url":"https://api.github.com/users/MarshallOfSound/followers","following_url":"https://api.github.com/users/MarshallOfSound/following{/other_user}","gists_url":"https://api.github.com/users/MarshallOfSound/gists{/gist_id}","starred_url":"https://api.github.com/users/MarshallOfSound/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/MarshallOfSound/subscriptions","organizations_url":"https://api.github.com/users/MarshallOfSound/orgs","repos_url":"https://api.github.com/users/MarshallOfSound/repos","events_url":"https://api.github.com/users/MarshallOfSound/events{/privacy}","received_events_url":"https://api.github.com/users/MarshallOfSound/received_events","type":"User","site_admin":false},"assignees":[{"login":"MarshallOfSound","id":6634592,"avatar_url":"https://avatars.githubusercontent.com/u/6634592?v=3","gravatar_id":"","url":"https://api.github.com/users/MarshallOfSound","html_url":"https://github.com/MarshallOfSound","followers_url":"https://api.github.com/users/MarshallOfSound/followers","following_url":"https://api.github.com/users/MarshallOfSound/following{/other_user}","gists_url":"https://api.github.com/users/MarshallOfSound/gists{/gist_id}","starred_url":"https://api.github.com/users/MarshallOfSound/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/MarshallOfSound/subscriptions","organizations_url":"https://api.github.com/users/MarshallOfSound/orgs","repos_url":"https://api.github.com/users/MarshallOfSound/repos","events_url":"https://api.github.com/users/MarshallOfSound/events{/privacy}","received_events_url":"https://api.github.com/users/MarshallOfSound/received_events","type":"User","site_admin":false}],"milestone":null,"comments":4,"created_at":"2016-09-24T09:14:46Z","updated_at":"2016-09-25T10:28:50Z","closed_at":null,"body":"* Electron version: All\r\n* Operating system: All\r\n\r\nCurrently the JSON API doesn't contain return values from methods, this makes converting the JSON to a `.d.ts` file quite difficult as we just assume that methods return `void` or `any`.\r\n\r\nI would suggest the return standard being something like this.\r\n\r\n```markdown\r\n### `app.getName()`\r\n\r\nReturns `String` - The current application's name, which is the name in the application's\r\n`package.json` file.\r\n\r\nUsually the `name` field of `package.json` is a short lowercased name, according\r\nto the npm modules spec. You should usually also specify a `productName`\r\nfield, which is your application's full capitalized name, and which will be\r\npreferred over `name` by Electron.\r\n```\r\n\r\nI.e. If a method has a return value, specify it in the first paragraph of the description in the following format\r\n\r\n```markdown\r\nReturns `[TYPE]` - Description of return value\r\n```\r\n\r\n/cc @zeke "},"comment":{"url":"https://api.github.com/repos/electron/electron/issues/comments/249414185","html_url":"https://github.com/electron/electron/issues/7337#issuecomment-249414185","issue_url":"https://api.github.com/repos/electron/electron/issues/7337","id":249414185,"user":{"login":"enlight","id":233003,"avatar_url":"https://avatars.githubusercontent.com/u/233003?v=3","gravatar_id":"","url":"https://api.github.com/users/enlight","html_url":"https://github.com/enlight","followers_url":"https://api.github.com/users/enlight/followers","following_url":"https://api.github.com/users/enlight/following{/other_user}","gists_url":"https://api.github.com/users/enlight/gists{/gist_id}","starred_url":"https://api.github.com/users/enlight/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/enlight/subscriptions","organizations_url":"https://api.github.com/users/enlight/orgs","repos_url":"https://api.github.com/users/enlight/repos","events_url":"https://api.github.com/users/enlight/events{/privacy}","received_events_url":"https://api.github.com/users/enlight/received_events","type":"User","site_admin":false},"created_at":"2016-09-25T10:28:50Z","updated_at":"2016-09-25T10:28:50Z","body":"@MarshallOfSound summarized the proposed changes in #7339 as follows:\r\n>I think the key thing here is the difference between human readable documentation and clear / accurate / formatted documentation. A think this a compromise between the two (both readable and follows an exact format).\r\n\r\nI have a counter proposal that aims to maximize readability, some examples:\r\n\r\nProposal in OP:\r\n```markdown\r\n### `app.getName()`\r\n\r\nReturns `String` - The current application's name, which is the name in the application's\r\n`package.json` file.\r\n```\r\n\r\nVS\r\n\r\n```markdown\r\n### `app.getName()`\r\n\r\nReturns a `String` with the application's name, which is the name in the application's\r\n`package.json` file.\r\n```\r\n\r\nAnd with array types:\r\n\r\n```markdown\r\n#### `BrowserWindow.getAllWindows()`\r\n \r\nReturns `BrowserWindow[]` - An array of all opened browser windows.\r\n```\r\n\r\nVS\r\n\r\n```markdown\r\n#### `BrowserWindow.getAllWindows()`\r\n \r\nReturns an array of `BrowserWindow` instances that correspond to all the existing\r\nbrowser windows.\r\n```\r\n\r\nAnd with object types:\r\n\r\n```markdown\r\n#### `win.getContentBounds()`\r\n\r\n+Returns `Object`:\r\n+* `width` Integer\r\n+* `height` Integer\r\n+* `x` Integer\r\n+* `y` Integer\r\n```\r\n\r\nVS\r\n\r\n```markdown\r\n#### `win.getContentBounds()`\r\n\r\nReturns an `Object` containing the bounds of the window's client area (e.g. the web page):\r\n* `width` `Integer`\r\n* `height` `Integer`\r\n* `x` `Integer`\r\n* `y` `Integer`\r\n```\r\n\r\nSo the alternative format can be summarized as:\r\n\r\n```markdown\r\nReturns [a|an|the] [array of] [TYPE] [-] description\r\n\r\nReturns [a|an|the] [array of] [TYPE] [-] description [:]\r\n* `propName` `TYPE` [- description]\r\n* `propName` `TYPE` [- description]\r\n```\r\n\r\nObviously my proposal requires the parser to do more work, and I'm not the one writing the parser, so I'll be happy with whatever."}}
{"actor":{"display_login":"enlight"}}