Incorrect JSDoc for a variety of methods

[ipotuzhnov]

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 npm module.

Here are some of the issues:

• Table#read 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, but in fact that array only contains rows.
• BatchTransaction#execute method's callback argument should be optional
• Instance#setMetadata object should start with capital O for metadata argument
• Database#run 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.
• For some methods that return promises the type of the resolved value is not specified
• Some types are misspelled. Should be Error instead of error and Date instead of date, unless I've missed typedefs for those types.

Environment details

• OS: N/A
• Node.js version: N/A
• npm version: N/A
• @google-cloud/spanner version: 2.0.0

Steps to reproduce

git checkout v2.0.0
npm install
npm install --no-save @otris/jsdoc-tsd typescript
# Convert the `.jsdoc.js` file into JSON
node -e "console.log(JSON.stringify(require('./.jsdoc'),null,2))" > .jsdoc-dts.json
# Generate a `.d.ts` file 
$(npm bin)/jsdoc -c .jsdoc-dts.json -t ./node_modules/@otris/jsdoc-tsd -d spanner.d.ts
$(npm bin)/tsc --noEmit spanner.d.ts

Following these steps will guarantee the quickest resolution possible.

Map the errors returned by TypeScript compiler to the actual code and fix the documentation.

There 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.
I'm pretty sure there are some other means to validate JSDoc as well.

Thanks!

PS.: I'd be glad to submit a PR(s) to fix some of this issues.

[callmehiphop]

@ipotuzhnov thanks for reporting! I went ahead and made a PR (#352) with a number of JSDoc fixes. I ended up going with eslint's valid-jsdoc rule, so I'm not 100% sure that this will entirely fix the issues you're seeing, but if you get a chance to test it out that would be super appreciated!

[ipotuzhnov]

@callmehiphop Thank you for looking into it! I think using valid-jsdoc eslint rule is a great idea. Probably it doesn't check if all the types exist and are valid, but that's a good start.

Unfortunately, @otris/jsdoc-tsd fails to parse jsdoc on master, so I'll need to figure out what's causing it to crash before I can test it.