Improved documentation

speech_to_text/example/lib/main.dart

@@ -123,7 +123,7 @@ class _SpeechSampleAppState extends State<SpeechSampleApp> {
     lastError = '';
     final pauseFor = int.tryParse(_pauseForController.text);
     final listenFor = int.tryParse(_listenForController.text);
-    // Note that `listenFor` is the maximum, not the minimun, on some
+    // Note that `listenFor` is the maximum, not the minimum, on some
     // systems recognition will be stopped before this value is reached.
     // Similarly `pauseFor` is a maximum not a minimum and may be ignored
     // on some devices.

speech_to_text/lib/speech_recognition_error.dart

@@ -6,7 +6,7 @@ part 'speech_recognition_error.g.dart';
 ///
 /// Errors are either transient or permanent. Permanent errors
 /// block speech recognition from continuing and must be
-/// addressed before recogntion will work. Transient errors
+/// addressed before recognition will work. Transient errors
 /// cause individual recognition sessions to fail but subsequent
 /// attempts may well succeed.
 @JsonSerializable()

speech_to_text/lib/speech_recognition_result.dart

@@ -19,7 +19,7 @@ class SpeechRecognitionResult {
   /// value. Use the confidence for each alternate transcription
   /// to determine how likely it is. Note that not all platforms
   /// do a good job with confidence, there are convenience methods
-  /// on [SpeechRecogntionWords] to work with possibly missing
+  /// on [SpeechRecognitionWords] to work with possibly missing
   /// confidence values.
   // TODO: Fix up the interface.
   // List<SpeechRecognitionWords> get alternates =>
@@ -55,7 +55,7 @@ class SpeechRecognitionResult {
           ? alternates.first.isConfident(threshold: threshold)
           : false;
 
-  /// true if [confidence] is not the [missingConfidence] value, false
+  /// true if [confidence] is not the [SpeechRecognitionWords.missingConfidence] value, false
   /// otherwise.
   bool get hasConfidenceRating =>
       alternates.isNotEmpty ? alternates.first.hasConfidenceRating : false;

speech_to_text/lib/speech_to_text.dart

@@ -9,68 +9,88 @@ import 'package:speech_to_text/speech_recognition_error.dart';
 import 'package:speech_to_text/speech_recognition_result.dart';
 import 'package:speech_to_text_platform_interface/speech_to_text_platform_interface.dart';
 
+/// Describes the goal of your speech recognition to the system.
+///
+/// Currently only supported on **iOS**.
+///
+/// See also:
+/// * https://developer.apple.com/documentation/speech/sfspeechrecognitiontaskhint
 enum ListenMode {
+  /// The device default.
   deviceDefault,
+
+  /// When using captured speech for text entry.
+  ///
+  /// Use this when you are using speech recognition for a task that's similar to the keyboard's built-in dictation function.
   dictation,
+
+  /// When using captured speech to specify search terms.
+  ///
+  /// Use this when you are using speech recognition to identify search terms.
   search,
+
+  /// When using captured speech for short, confirmation-style requests.
+  ///
+  /// Use this when you are using speech recognition to handle confirmation commands, such as "yes", "no" or "maybe".
   confirmation,
 }
 
 /// A single locale with a [name], localized to the current system locale,
-/// and a [localeId] which can be used in the [listen] method to choose a
+/// and a [localeId] which can be used in the [SpeechToText.listen] method to choose a
 /// locale for speech recognition.
 class LocaleName {
   final String localeId;
   final String name;
+
   LocaleName(this.localeId, this.name);
 }
 
 /// Notified as words are recognized with the current set of recognized words.
 ///
-/// See the [onResult] argument on the [listen] method for use.
+/// See the [onResult] argument on the [SpeechToText.listen] method for use.
 typedef SpeechResultListener = void Function(SpeechRecognitionResult result);
 
-/// Notified if errors occur during recognition or intialization.
+/// Notified if errors occur during recognition or initialization.
 ///
 /// Possible errors per the Android docs are described here:
 /// https://developer.android.com/reference/android/speech/SpeechRecognizer
-///   "error_audio_error"
-///   "error_client"
-///   "error_permission"
-///   "error_network"
-///   "error_network_timeout"
-///   "error_no_match"
-///   "error_busy"
-///   "error_server"
-///   "error_speech_timeout"
-///   "error_language_not_supported"
-///   "error_language_unavailable"
-///   "error_server_disconnected"
-///   "error_too_many_requests"
+/// * "error_audio_error"
+/// * "error_client"
+/// * "error_permission"
+/// * "error_network"
+/// * "error_network_timeout"
+/// * "error_no_match"
+/// * "error_busy"
+/// * "error_server"
+/// * "error_speech_timeout"
+/// * "error_language_not_supported"
+/// * "error_language_unavailable"
+/// * "error_server_disconnected"
+/// * "error_too_many_requests"
 ///
 /// iOS errors are not well documented in the iOS SDK, so far these are the
 /// errors that have been observed:
-///   "error_speech_recognizer_disabled"
-///   "error_retry"
-///   "error_no_match"
+/// * "error_speech_recognizer_disabled"
+/// * "error_retry"
+/// * "error_no_match"
 ///
 /// Both platforms use this message for an unrecognized error:
-///   "error_unknown ($errorCode)" where $errorCode provides more detail
-
-/// See the [onError] argument on the [initialize] method for use.
+/// * "error_unknown ($errorCode)" where `$errorCode` provides more detail
+///
+/// See the [onError] argument on the [SpeechToText.initialize] method for use.
 typedef SpeechErrorListener = void Function(
     SpeechRecognitionError errorNotification);
 
 /// Notified when recognition status changes.
 ///
-/// See the [onStatus] argument on the [initialize] method for use.
+/// See the [onStatus] argument on the [SpeechToText.initialize] method for use.
 typedef SpeechStatusListener = void Function(String status);
 
 /// Notified when the sound level changes during a listen method.
 ///
 /// [level] is a measure of the decibels of the current sound on
 /// the recognition input. See the [onSoundLevelChange] argument on
-/// the [listen] method for use.
+/// the [SpeechToText.listen] method for use.
 typedef SpeechSoundLevelChange = Function(double level);
 
 /// An interface to device specific speech recognition services.
@@ -216,6 +236,7 @@ class SpeechToText {
   ///
   /// Also goes false when listening times out if listenFor was set.
   bool get isListening => _listening;
+
   bool get isNotListening => !isListening;
 
   /// The last error received or null if none, see [initialize] to
@@ -242,6 +263,7 @@ class SpeechToText {
   /// successful, false if failed.
   ///
   /// This method must be called before any other speech functions.
+  ///
   /// If this method returns false no further [SpeechToText] methods
   /// should be used. Should only be called once if successful but does protect
   /// itself if called repeatedly. False usually means that the user has denied
@@ -250,22 +272,26 @@ class SpeechToText {
   ///
   /// [onError] is an optional listener for errors like
   /// timeout, or failure of the device speech recognition.
+  ///
   /// [onStatus] is an optional listener for status changes. There are three
   /// possible status values:
-  /// - 'listening' when speech recognition begins after calling the [listen]
-  /// method;
-  /// - 'notListening' when speech recognition is no longer listening to the
-  /// microphone after a timeout, [cancel] or [stop] call;
-  /// - 'done' when all results have been delivered.
+  /// * `listening` when speech recognition begins after calling the [listen]
+  /// method.
+  /// * `notListening` when speech recognition is no longer listening to the
+  /// microphone after a timeout, [cancel] or [stop] call.
+  /// * `done` when all results have been delivered.
+  ///
   /// [debugLogging] controls whether there is detailed logging from the
   /// underlying platform code. It is off by default, usually only useful
-  /// for troubleshooting issueswith a paritcular OS version or device,
+  /// for troubleshooting issues with a particular OS version or device,
   /// fairly verbose
+  ///
   /// [finalTimeout] a duration to wait for a final result from the device
   /// speech recognition service. If no final result is received within this
   /// time the last partial result is returned as final. This defaults to
   /// two seconds. A duration of fifty milliseconds or less disables the
   /// check and final results will only be returned from the device.
+  ///
   /// [options] pass platform specific configuration options to the
   /// platform specific implementation.
   Future<bool> initialize(
@@ -368,7 +394,7 @@ class SpeechToText {
   ///
   /// [onSoundLevelChange] is an optional listener that is notified when the
   /// sound level of the input changes. Use this to update the UI in response to
-  /// more or less input. The values currently differ between Ancroid and iOS,
+  /// more or less input. The values currently differ between Android and iOS,
   /// haven't yet been able to determine from the Android documentation what the
   /// value means. On iOS the value returned is in decibels.
   ///
@@ -391,8 +417,7 @@ class SpeechToText {
   ///
   /// [sampleRate] optional for compatibility with certain iOS devices, some devices
   /// crash with `sampleRate != device's supported sampleRate`, try 44100 if seeing
-  /// crashes
-  ///
+  /// crashes.
   Future listen(
       {SpeechResultListener? onResult,
       Duration? listenFor,
@@ -489,12 +514,12 @@ class SpeechToText {
     _listenTimer = Timer(minDuration, _stopOnPauseOrListen);
   }
 
-  /// milliseconds since the last listen was started, this is used for
+  /// Milliseconds since the last listen was started, this is used for
   /// the listen for calculations
   int get _elapsedListenMillis =>
       clock.now().millisecondsSinceEpoch - _listenStartedAt;
 
-  /// milliseconds since the last speech event was detected, this
+  /// Milliseconds since the last speech event was detected, this
   /// is used for the pause calculations
   int get _elapsedSinceSpeechEvent =>
       clock.now().millisecondsSinceEpoch - _lastSpeechEventAt;
@@ -513,7 +538,7 @@ class SpeechToText {
     }
   }
 
-  /// returns the list of speech locales available on the device or those
+  /// Returns the list of speech locales available on the device or those
   /// supported by the speech recognizer on the device.
   ///
   /// Being on this list does not guarantee that the device will be able to
@@ -554,7 +579,7 @@ class SpeechToText {
     return filteredLocales;
   }
 
-  /// returns the locale that will be used if no localeId is passed
+  /// Returns the locale that will be used if no localeId is passed
   /// to the [listen] method.
   Future<LocaleName?> systemLocale() async {
     if (null == _systemLocale) {
@@ -631,8 +656,8 @@ class SpeechToText {
       case _finalStatus:
         if (!_notifiedDone) return;
 
-        /// the [_finalStatus] is just to indicate that it can send the
-        /// [doneStatus] if [_notifiedDone] has already happened.
+        // the [_finalStatus] is just to indicate that it can send the
+        // [doneStatus] if [_notifiedDone] has already happened.
         status = doneStatus;
         break;
       case _doneNoResultStatus:
@@ -674,11 +699,12 @@ class SpeechToText {
 class SpeechToTextNotInitializedException implements Exception {}
 
 /// Thrown when listen fails to properly start a speech listening session
-/// on the device
+/// on the device.
 class ListenFailedException implements Exception {
   final String? message;
   final String? details;
   final String? stackTrace;
+
   ListenFailedException(this.message, [this.details, this.stackTrace]);
 }
 

speech_to_text/lib/speech_to_text_web.dart

@@ -17,7 +17,7 @@ class SpeechToTextPlugin extends SpeechToTextPlatform {
   bool _resultSent = false;
   bool _doneSent = false;
 
-  /// Registers this class as the default instance of [UrlLauncherPlatform].
+  /// Registers this class as the default instance of [SpeechToTextPlatform].
   static void registerWith(Registrar registrar) {
     SpeechToTextPlatform.instance = SpeechToTextPlugin();
   }
@@ -45,7 +45,7 @@ class SpeechToTextPlugin extends SpeechToTextPlatform {
   ///
   /// [debugLogging] controls whether there is detailed logging from the underlying
   /// plugins. It is off by default, usually only useful for troubleshooting issues
-  /// with a paritcular OS version or device, fairly verbose
+  /// with a particular OS version or device, fairly verbose
   @override
   Future<bool> initialize(
       {debugLogging = false, List<SpeechConfigOption>? options}) async {

speech_to_text_macos/lib/speech_to_text_macos.dart

@@ -33,7 +33,7 @@ class SpeechToTextMacOS extends SpeechToTextPlatform {
   ///
   /// [debugLogging] controls whether there is detailed logging from the underlying
   /// plugins. It is off by default, usually only useful for troubleshooting issues
-  /// with a paritcular OS version or device, fairly verbose
+  /// with a particular OS version or device, fairly verbose
   @override
   Future<bool> initialize(
       {debugLogging = false, List<SpeechConfigOption>? options}) async {

speech_to_text_platform_interface/lib/speech_to_text_platform_interface.dart

@@ -81,7 +81,7 @@ abstract class SpeechToTextPlatform extends PlatformInterface {
   ///
   /// [debugLogging] controls whether there is detailed logging from the underlying
   /// plugins. It is off by default, usually only useful for troubleshooting issues
-  /// with a paritcular OS version or device, fairly verbose
+  /// with a particular OS version or device, fairly verbose
   Future<bool> initialize(
       {debugLogging = false, List<SpeechConfigOption>? options}) {
     throw UnimplementedError('initialize() has not been implemented.');