@example Comments should refer to sample code

[sduskis]

nodejs-bigtable has @example comments that include code. This is error prone, since it's not compiled and may get obsolete. Instead of inline code, all @examples should refer to a sample file and a tag within it.

nodejs-spanner has a great examples of this. Here's one example (link):

/**
 ...
 * @example <caption>include:samples/batch.js</caption>
 * region_tag:spanner_batch_client
*/

[vijay-qlogic]

@sduskis Shall I start adding this @example comment? start with src/instance.js which has example code in sample/instances.js

[sduskis]

@vijay-qlogic, please do.

[vijay-qlogic]

@sduskis Currently src/instance.js has @example comments with multiple ways to call a method.
Like: using callback, promise (when callback is omitted)
And in sample/instances.js we have used async/await
Shall we update sample/instances.js to cover all these format? Or how we should go ahead?
your thoughts please...

[sduskis]

The sample/instances.js is meant to show basic situations. If we need more options, then we probably need to create additional files somewhere. Do unit tests or system test work well enough for this type of thing?