{"action":"opened","issue":{"url":"https://api.github.com/repos/googleapis/nodejs-spanner/issues/345","repository_url":"https://api.github.com/repos/googleapis/nodejs-spanner","labels_url":"https://api.github.com/repos/googleapis/nodejs-spanner/issues/345/labels{/name}","comments_url":"https://api.github.com/repos/googleapis/nodejs-spanner/issues/345/comments","events_url":"https://api.github.com/repos/googleapis/nodejs-spanner/issues/345/events","html_url":"https://github.com/googleapis/nodejs-spanner/issues/345","id":364265249,"node_id":"MDU6SXNzdWUzNjQyNjUyNDk=","number":345,"title":"Incorrect JSDoc for a variety of methods","user":{"login":"ipotuzhnov","id":6608426,"node_id":"MDQ6VXNlcjY2MDg0MjY=","avatar_url":"https://avatars2.githubusercontent.com/u/6608426?v=4","gravatar_id":"","url":"https://api.github.com/users/ipotuzhnov","html_url":"https://github.com/ipotuzhnov","followers_url":"https://api.github.com/users/ipotuzhnov/followers","following_url":"https://api.github.com/users/ipotuzhnov/following{/other_user}","gists_url":"https://api.github.com/users/ipotuzhnov/gists{/gist_id}","starred_url":"https://api.github.com/users/ipotuzhnov/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ipotuzhnov/subscriptions","organizations_url":"https://api.github.com/users/ipotuzhnov/orgs","repos_url":"https://api.github.com/users/ipotuzhnov/repos","events_url":"https://api.github.com/users/ipotuzhnov/events{/privacy}","received_events_url":"https://api.github.com/users/ipotuzhnov/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":0,"created_at":"2018-09-27T00:54:52Z","updated_at":"2018-09-27T00:54:52Z","closed_at":null,"author_association":"NONE","body":"I found some discrepancies between implementation and documentation when I've tried to generate a `.d.ts` file based on JSDoc with [@otris/jsdoc-tsd](https://www.npmjs.com/package/@otris/jsdoc-tsd) npm module.\r\n\r\nHere are some of the issues:\r\n- [Table#read](https://github.com/googleapis/nodejs-spanner/blob/master/src/table.js#L518) method is not documented (or implemented?) correctly. When the example is consistent with the current behavior there is some discrepancy with the documentation. The documentation says that the returned promise resolves to an array containing an instance of a Table and an array of rows (objects) [TableReadResponse](https://github.com/googleapis/nodejs-spanner/blob/master/src/table.js#L389), but in fact that array only contains rows.\r\n- [BatchTransaction#execute](https://github.com/googleapis/nodejs-spanner/blob/master/src/batch-transaction.js#L228) method's [callback argument](https://github.com/googleapis/nodejs-spanner/blob/master/src/batch-transaction.js#L221) should be optional\r\n- [Instance#setMetadata](https://github.com/googleapis/nodejs-spanner/blob/master/src/instance.js#L625) `object` should start with capital O for [metadata argument](https://github.com/googleapis/nodejs-spanner/blob/master/src/instance.js#L591)\r\n- [Database#run](https://github.com/googleapis/nodejs-spanner/blob/master/src/database.js#L1141) method takes `string` or `object` as the first argument, so probably there should be a separate `@typedef` for that `object`, but I'm not sure.\r\n- For some methods that return promises the type of the resolved value is not specified\r\n- Some types are misspelled. Should be `Error` instead of `error` and `Date` instead of `date`, unless I've missed typedefs for those types.\r\n\r\n#### Environment details\r\n\r\n  - OS: N/A\r\n  - Node.js version: N/A\r\n  - npm version: N/A\r\n  - `@google-cloud/spanner` version: 2.0.0\r\n\r\n#### Steps to reproduce\r\n\r\n```bash\r\ngit checkout v2.0.0\r\nnpm install\r\nnpm install --no-save @otris/jsdoc-tsd typescript\r\n# Convert the `.jsdoc.js` file into JSON\r\nnode -e \"console.log(JSON.stringify(require('./.jsdoc'),null,2))\" > .jsdoc-dts.json\r\n# Generate a `.d.ts` file \r\n$(npm bin)/jsdoc -c .jsdoc-dts.json -t ./node_modules/@otris/jsdoc-tsd -d spanner.d.ts\r\n$(npm bin)/tsc --noEmit spanner.d.ts\r\n```\r\n\r\nFollowing these steps will guarantee the quickest resolution possible.\r\n\r\nMap the errors returned by TypeScript compiler to the actual code and fix the documentation.\r\n\r\nThere is a way to configure TypeScript compiler to check JavaScript files (it will also pick up JSDoc comments as type annotations), but that could result in too much noise if you only want to check that the documentation is valid.\r\nI'm pretty sure there are some other means to validate JSDoc as well.\r\n\r\nThanks!\r\n\r\nPS.: I'd be glad to submit a PR(s) to fix some of this issues."}}
{"actor":{"display_login":"ipotuzhnov"}}