Google-cloud-node: New Samples Not Copy-Pastable

[anguillanneuf]

This may beg for a lengthier discussion somewhere else, but I'm filing it as a bug here just in case it counts as one.

All the code samples in /samples now use await, but await is only valid in async function, which means that the samples can't be run if someone just copies and pastes the code. This is different from what we are striving for across all our samples.

[stephenplusplus]

I agree, we should probably use this as a model: https://github.com/googleapis/nodejs-pubsub/blob/b642898736d8143f6732cd1ed5a8f7279bc6c8c8/samples/quickstart.js#L18

// [START pubsub_quickstart_create_topic]
// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

async function quickstart() {
  // Your Google Cloud Platform project ID
  const projectId = process.env.GCLOUD_PROJECT || 'YOUR_PROJECT_ID';

  // Instantiates a client
  const pubsubClient = new PubSub({
    projectId: projectId,
  });

  // The name for the new topic
  const topicName = 'my-topic';

  // Creates the new topic
  const [topic] = await pubsubClient.createTopic(topicName);
  console.log(`Topic ${topic.name} created.`);
}
quickstart().catch(console.error);
// [END pubsub_quickstart_create_topic]

Before

async function listSubscriptions() {
  // [START pubsub_list_subscriptions]
  // Imports the Google Cloud client library
  const {PubSub} = require('@google-cloud/pubsub');

  // Creates a client
  const pubsub = new PubSub();

  // Lists all subscriptions in the current project
  const [subscriptions] = await pubsub.getSubscriptions();
  console.log('Subscriptions:');
  subscriptions.forEach(subscription => console.log(subscription.name));

  // [END pubsub_list_subscriptions]
}

After

// [START pubsub_list_subscriptions]
// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

async function listSubscriptions() {
  // Creates a client
  const pubsub = new PubSub();

  // Lists all subscriptions in the current project
  const [subscriptions] = await pubsub.getSubscriptions();
  console.log('Subscriptions:');
  subscriptions.forEach(subscription => console.log(subscription.name));
}

listSubscriptions().catch(console.error);
// [END pubsub_list_subscriptions]

[JustinBeckwith]

That makes a lot of sense. We absolutely want to keep the async/await, but shifting things around like this makes a ton of sense.

Adding @fhinkel so she can chime in here as well.

[fhinkel]

The REPL allows for top level async await if you start it with the right flag. So we're not quite there yet.

+1 to the examples @stephenplusplus posted.

[fhinkel]

So, the other day I fell into the "trap" of copying and pasting a sample without an async function around it. Yes, I had to go back, write 1.5 lines of code, and run the sample again. But in the end, I'd say that's not too bad. Searching for the error message takes you straight to the right StackOverflow answer.

And the example looked really nice without the async function... boilerplate code. I think it's fine to keep samples that don't work with only copy&paste.

[JustinBeckwith]

@fhinkel This sounds like the sort of thing that should be covered in the new rubric. Do we have all the rules of the road for nodejs docs documented in a single place? I'd just love to not have to rehash these kinds of decisions :)

[fhinkel]

so we have these two proposals:

https://github.com/googleapis/nodejs-speech/pull/199/files
https://github.com/googleapis/nodejs-dlp/pull/154/files

In those, the function signature is always included in the snippet - but all snippets are very long, too.

I don't know what the state of the rubric is. Can we still make changes?

[JustinBeckwith]

🤷‍♂️

@jmdobry ?

[jmdobry]

I hope to have this finalized in the coming days.