Speech: clarify comments. [(#1278)](#1278)

speech/snippets/transcribe.py

@@ -51,8 +51,10 @@ def transcribe_file(speech_file):
     # [START migration_sync_response]
     response = client.recognize(config, audio)
     # [END migration_sync_request]
-    # Print the first alternative of all the consecutive results.
+    # Each result is for a consecutive portion of the audio. Iterate through
+    # them to get the transcripts for the entire audio file.
     for result in response.results:
+        # The first alternative is the most likely one for this portion.
         print('Transcript: {}'.format(result.alternatives[0].transcript))
     # [END migration_sync_response]
 # [END def_transcribe_file]
@@ -75,8 +77,10 @@ def transcribe_gcs(gcs_uri):
     # [END migration_audio_config_gcs]
 
     response = client.recognize(config, audio)
-    # Print the first alternative of all the consecutive results.
+    # Each result is for a consecutive portion of the audio. Iterate through
+    # them to get the transcripts for the entire audio file.
     for result in response.results:
+        # The first alternative is the most likely one for this portion.
         print('Transcript: {}'.format(result.alternatives[0].transcript))
 # [END def_transcribe_gcs]
 

speech/snippets/transcribe_async.py

@@ -51,8 +51,10 @@ def transcribe_file(speech_file):
     print('Waiting for operation to complete...')
     response = operation.result(timeout=90)
 
-    # Print the first alternative of all the consecutive results.
+    # Each result is for a consecutive portion of the audio. Iterate through
+    # them to get the transcripts for the entire audio file.
     for result in response.results:
+        # The first alternative is the most likely one for this portion.
         print('Transcript: {}'.format(result.alternatives[0].transcript))
         print('Confidence: {}'.format(result.alternatives[0].confidence))
     # [END migration_async_response]
@@ -78,8 +80,10 @@ def transcribe_gcs(gcs_uri):
     print('Waiting for operation to complete...')
     response = operation.result(timeout=90)
 
-    # Print the first alternative of all the consecutive results.
+    # Each result is for a consecutive portion of the audio. Iterate through
+    # them to get the transcripts for the entire audio file.
     for result in response.results:
+        # The first alternative is the most likely one for this portion.
         print('Transcript: {}'.format(result.alternatives[0].transcript))
         print('Confidence: {}'.format(result.alternatives[0].confidence))
 # [END def_transcribe_gcs]

speech/snippets/transcribe_streaming.py

@@ -55,10 +55,14 @@ def transcribe_streaming(stream_file):
     # [END migration_streaming_request]
 
     for response in responses:
+        # Once the transcription has settled, the first result will contain the
+        # is_final result. The other results will be for subsequent portions of
+        # the audio.
         for result in response.results:
             print('Finished: {}'.format(result.is_final))
             print('Stability: {}'.format(result.stability))
             alternatives = result.alternatives
+            # The alternatives are ordered from most likely to least.
             for alternative in alternatives:
                 print('Confidence: {}'.format(alternative.confidence))
                 print('Transcript: {}'.format(alternative.transcript))