Cleaning up comments in interface for TTS engines.

1 files changed, 73 insertions, 44 deletions

diff --git a/include/tts/TtsEngine.h b/include/tts/TtsEngine.h
index e0220ea..d2aa30e 100644
--- a/include/tts/TtsEngine.h
+++ b/include/tts/TtsEngine.h
@@ -16,9 +16,10 @@
 #include <media/AudioSystem.h>
 
 // This header defines the interface used by the Android platform
-// to access Text-To-Speech functionality in shared libraries that implement speech
-// synthesis and the management of resources associated with the synthesis.
-// An example of the implementation of this interface can be found in 
+// to access Text-To-Speech functionality in shared libraries that implement
+// speech synthesis and the management of resources associated with the
+// synthesis.
+// An example of the implementation of this interface can be found in
 // FIXME: add path+name to implementation of default TTS engine
 // Libraries implementing this interface are used in:
 //  frameworks/base/tts/jni/android_tts_SpeechSynthesis.cpp
@@ -39,15 +40,21 @@ enum tts_callback_status {
 // client, the Android TTS service, that the last requested synthesis has been
 // completed. // TODO reword
 // The callback for synthesis completed takes:
-//    [inout] void *&      - The userdata pointer set in the original synth call
-//    [in]    uint32_t     - Track sampling rate in Hz
-//    [in]    audio_format - The AudioSystem::audio_format enum
-//    [in]    int          - The number of channels
-//    [inout] int8_t *&     - A buffer of audio data only valid during the execution of the callback
-//    [inout] size_t  &     - The size of the buffer
-//    [in]    tts_synth_status  - Status of the synthesis; 0 for done, 1 for more data to be synthesized.
-// Returns the status of the consumer of the synthesis. 0 for stop, 1 for continue.
-typedef tts_callback_status (synthDoneCB_t)(void *&, uint32_t, AudioSystem::audio_format, int, int8_t *&, size_t&, tts_synth_status);
+// @param [inout] void *&       - The userdata pointer set in the original
+//                                 synth call
+// @param [in]    uint32_t      - Track sampling rate in Hz
+// @param [in]    audio_format  - The AudioSystem::audio_format enum
+// @param [in]    int           - The number of channels
+// @param [inout] int8_t *&     - A buffer of audio data only valid during the
+//                                execution of the callback
+// @param [inout] size_t  &     - The size of the buffer
+// @param [in] tts_synth_status - indicate whether the synthesis is done, or
+//                                 if more data is to be synthesized.
+// @return TTS_CALLBACK_HALT to indicate the synthesis must stop,
+//         TTS_CALLBACK_CONTINUE to indicate the synthesis must continue if
+//            there is more data to produce.
+typedef tts_callback_status (synthDoneCB_t)(void *&, uint32_t,
+        AudioSystem::audio_format, int, int8_t *&, size_t&, tts_synth_status);
 
 class TtsEngine;
 extern "C" TtsEngine* getTtsEngine();
@@ -74,38 +81,41 @@ public:
     // @return TTS_SUCCESS, or TTS_FAILURE
     virtual tts_result shutdown();
 
-    // Interrupt synthesis and flushes any synthesized data that hasn't been output yet.
-    // This will block until callbacks underway are completed.
+    // Interrupt synthesis and flushes any synthesized data that hasn't been
+    // output yet. This will block until callbacks underway are completed.
     // @return TTS_SUCCESS, or TTS_FAILURE
     virtual tts_result stop();
 
-    // Load the resources associated with the specified language. The loaded language will
-    // only be used once a call to setLanguage() with the same language value is issued.
-    // Language values are based on the Android conventions for localization as described in
-    // the Android platform documentation on internationalization. This implies that language
-    // data is specified in the format xx-rYY, where xx is a two letter ISO 639-1 language code
-    // in lowercase and rYY is a two letter ISO 3166-1-alpha-2 language code in uppercase
-    // preceded by a lowercase "r".
+    // Load the resources associated with the specified language. The loaded
+    // language will only be used once a call to setLanguage() with the same
+    // language value is issued. Language values are based on the Android
+    // conventions for localization as described in the Android platform
+    // documentation on internationalization. This implies that language
+    // data is specified in the format xx-rYY, where xx is a two letter
+    // ISO 639-1 language code in lowercase and rYY is a two letter
+    // ISO 3166-1-alpha-2 language code in uppercase preceded by a
+    // lowercase "r".
     // @param value pointer to the language value
     // @param size  length of the language value
     // @return TTS_SUCCESS, or TTS_FAILURE
     virtual tts_result loadLanguage(const char *value, const size_t size);
 
-    // Signal the engine to use the specified language. This will force the language to be
-    // loaded if it wasn't loaded previously with loadLanguage().
+    // Signal the engine to use the specified language. This will force the
+    // language to be loaded if it wasn't loaded previously with loadLanguage().
     // See loadLanguage for the specification of the language.
     // @param value pointer to the language value
     // @param size  length of the language value
     // @return TTS_SUCCESS, or TTS_FAILURE
     virtual tts_result setLanguage(const char *value, const size_t size);
 
-    // Retrieve the currently set language, or an empty "value" if no language has
-    // been set.
+    // Retrieve the currently set language, or an empty "value" if no language
+    // has been set.
     // @param[out]   value pointer to the retrieved language value
-    // @param[inout] iosize  in: stores the size available to store the language value in *value
-    //                       out: stores the size required to hold the language value if
-    //                         getLanguage() returned  TTS_PROPERTY_SIZE_TOO_SMALL,
-    //                         unchanged otherwise.
+    // @param[inout] iosize in: stores the size available to store the language
+    //                         value in *value
+    //                      out: stores the size required to hold the language
+    //                         value if  getLanguage() returned
+    //                         TTS_PROPERTY_SIZE_TOO_SMALL, unchanged otherwise.
     // @return TTS_SUCCESS, or TTS_PROPERTY_SIZE_TOO_SMALL, or TTS_FAILURE
     virtual tts_result getLanguage(char *value, size_t *iosize);
 
@@ -114,23 +124,31 @@ public:
     // @param property pointer to the property name
     // @param value    pointer to the property value
     // @param size     maximum size required to store this type of property
-    // @return         TTS_PROPERTY_UNSUPPORTED, or TTS_SUCCESS, or TTS_FAILURE, 
+    // @return         TTS_PROPERTY_UNSUPPORTED, or TTS_SUCCESS, or TTS_FAILURE,
     //                  or TTS_VALUE_INVALID
-    virtual tts_result setProperty(const char *property, const char *value, const size_t size);
+    virtual tts_result setProperty(const char *property, const char *value,
+            const size_t size);
 
     // Retrieve a property from the TTS engine
     // @param        property pointer to the property name
     // @param[out]   value    pointer to the retrieved language value
-    // @param[inout] iosize   in: stores the size available to store the property value
-    //                        out: stores the size required to hold the language value if
-    //                         getLanguage() returned  TTS_PROPERTY_SIZE_TOO_SMALL,
-    //                         unchanged otherwise.
-    // @return TTS_PROPERTY_UNSUPPORTED, or TTS_SUCCESS, or TTS_PROPERTY_SIZE_TOO_SMALL
-    virtual tts_result getProperty(const char *property, char *value, size_t *iosize);
+    // @param[inout] iosize   in: stores the size available to store the
+    //                          property value.
+    //                        out: stores the size required to hold the language
+    //                          value if getLanguage() returned
+    //                          TTS_PROPERTY_SIZE_TOO_SMALL, unchanged otherwise
+    // @return TTS_PROPERTY_UNSUPPORTED, or TTS_SUCCESS,
+    //         or TTS_PROPERTY_SIZE_TOO_SMALL
+    virtual tts_result getProperty(const char *property, char *value,
+            size_t *iosize);
 
     // Synthesize the text.
-    // When synthesis completes, the engine invokes the callback to notify the TTS framework.
-    // Note about the format of the input: the text parameter may use the following elements
+    // As the synthesis is performed, the engine invokes the callback to notify
+    // the TTS framework that it has filled the given buffer, and indicates how
+    // many bytes it wrote. The callback is called repeatedly until the engine
+    // has generated all the audio data corresponding to the text.
+    // Note about the format of the input: the text parameter may use the
+    // following elements
     // and their respective attributes as defined in the SSML 1.0 specification:
     //    * lang
     //    * say-as:
@@ -159,14 +177,25 @@ public:
     // Text is coded in UTF-8.
     // @param text      the UTF-8 text to synthesize
     // @param userdata  pointer to be returned when the call is invoked
+    // @param buffer    the location where the synthesized data must be written
+    // @param bufferSize the number of bytes that can be written in buffer
     // @return          TTS_SUCCESS or TTS_FAILURE
-    virtual tts_result synthesizeText(const char *text, int8_t *buffer, size_t bufferSize, void *userdata);
-
-    // Synthesize IPA text. When synthesis completes, the engine must call the given callback to notify the TTS API.
+    virtual tts_result synthesizeText(const char *text, int8_t *buffer,
+            size_t bufferSize, void *userdata);
+
+    // Synthesize IPA text.
+    // As the synthesis is performed, the engine invokes the callback to notify
+    // the TTS framework that it has filled the given buffer, and indicates how
+    // many bytes it wrote. The callback is called repeatedly until the engine
+    // has generated all the audio data corresponding to the IPA data.
     // @param ipa      the IPA data to synthesize
     // @param userdata  pointer to be returned when the call is invoked
-    // @return TTS_FEATURE_UNSUPPORTED if IPA is not supported, otherwise TTS_SUCCESS or TTS_FAILURE
-    virtual tts_result synthesizeIpa(const char *ipa, int8_t *buffer, size_t bufferSize, void *userdata);
+    // @param buffer    the location where the synthesized data must be written
+    // @param bufferSize the number of bytes that can be written in buffer
+    // @return TTS_FEATURE_UNSUPPORTED if IPA is not supported,
+    //         otherwise TTS_SUCCESS or TTS_FAILURE
+    virtual tts_result synthesizeIpa(const char *ipa, int8_t *buffer,
+            size_t bufferSize, void *userdata);
 };
 
 } // namespace android