code formatters sometimes break up sample metadata into multiple lines

[yihanzhen]

When we have a very long sample metadata:

// sample-metadata:
//   title: Transcribe Audio File using Long Running Operation (Local File) (LRO)
//   description: Transcribe a long audio file using asynchronous speech recognition
//   usage: gradle run -PmainClass=com.google.cloud.examples.speech.v1.SpeechTranscribeAsync [--args='[--local_file_path "resources/brooklyn_bridge.raw"]']

Formatters will think the last line is a comment because, well, it is a comment, and break it up:

// sample-metadata:
//   title: Transcribe Audio File using Long Running Operation (Local File) (LRO)
//   description: Transcribe a long audio file using asynchronous speech recognition
//   usage: gradle run -PmainClass=com.google.cloud.examples.speech.v1.SpeechTranscribeAsync
// [--args='[--local_file_path "resources/brooklyn_bridge.raw"]']

And therefore the YAML structure is broken.

While we can manually check line length and break the line up in the generator in a valid YAML syntax, it is quite lousy and probably hard to satisfy different languages.

The best way to solve this problem should be moving the metadata to the sample manifest file, because it is a real YAML :)

[yihanzhen]

cc/ @googleapis/samplegen Feel free to bump the priority.

[vchudnov-g]

There's been some very casual mention of having the metadata live in the manifest file, which would be the ideal place for it, especially since we already have it.

As I understand it, we are blocked on having the tooling that relies on the current metadata location changing to also get the metadata from manifest files. After that, we can do this.

I don't think this is a blocker for our "1.2" launch. Agreed?

[yihanzhen]

moved to backlog: https://github.com/googleapis/gapic-generator/wiki/feature-backlog