Cleaning up comments in interface for TTS engines.
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 @@
// 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 @@
// @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 @@
// @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 @@
// 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);
+ 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.
+ // 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