Fill in javadocs for translation feature.
Bug: 190236094
Test: atest CtsTranslationTestCases
Change-Id: I4d3e68cb4de4ca003f6f2cf1c0be626b91c0de97
diff --git a/core/java/android/service/translation/ITranslationService.aidl b/core/java/android/service/translation/ITranslationService.aidl
index e9dd2c3b..4cc732a 100644
--- a/core/java/android/service/translation/ITranslationService.aidl
+++ b/core/java/android/service/translation/ITranslationService.aidl
@@ -24,7 +24,7 @@
/**
* System-wide on-device translation service.
*
- * <p>Services requests to translate text between different languages. The primary use case for this
+ * <p>Services requests to translate data between different languages. The primary use case for this
* service is automatic translation of text and web views, when the auto Translate feature is
* enabled.
*
diff --git a/core/java/android/service/translation/TranslationService.java b/core/java/android/service/translation/TranslationService.java
index 93c006a..d454c39 100644
--- a/core/java/android/service/translation/TranslationService.java
+++ b/core/java/android/service/translation/TranslationService.java
@@ -48,6 +48,7 @@
import android.view.translation.TranslationRequest;
import android.view.translation.TranslationResponse;
import android.view.translation.TranslationSpec;
+import android.view.translation.Translator;
import com.android.internal.os.IResultReceiver;
@@ -81,7 +82,10 @@
* android.R.styleable#TranslationService translation-service}></code> tag.
*
* <p>Here's an example of how to use it on {@code AndroidManifest.xml}:
- * TODO: fill in doc example (check CCService/AFService).
+ * <pre> <translation-service
+ * android:settingsActivity="foo.bar.SettingsActivity"
+ * . . .
+ * /></pre>
*/
public static final String SERVICE_META_DATA = "android.translation_service";
@@ -148,7 +152,6 @@
void onTranslationSuccess(@NonNull TranslationResponse response);
/**
- * TODO: implement javadoc
* @removed use {@link #onTranslationSuccess} with an error response instead.
*/
@Deprecated
@@ -225,7 +228,7 @@
* should call back with {@code false}.</p>
*
* @param translationContext the {@link TranslationContext} of the session being created.
- * @param sessionId the int id of the session.
+ * @param sessionId the id of the session.
* @param callback {@link Consumer} to notify whether the session was successfully created.
*/
// TODO(b/176464808): the session id won't be unique cross client/server process. Need to find
@@ -234,8 +237,6 @@
int sessionId, @NonNull Consumer<Boolean> callback);
/**
- * TODO: fill in javadoc.
- *
* @removed use {@link #onCreateTranslationSession(TranslationContext, int, Consumer)}
* instead.
*/
@@ -246,19 +247,16 @@
}
/**
- * TODO: fill in javadoc.
+ * Called when a translation session is finished.
*
- * @param sessionId
+ * <p>The translation session is finished when the client calls {@link Translator#destroy()} on
+ * the corresponding translator.
+ *
+ * @param sessionId id of the session that finished.
*/
public abstract void onFinishTranslationSession(int sessionId);
/**
- * TODO: fill in javadoc.
- *
- * @param request
- * @param sessionId
- * @param callback
- * @param cancellationSignal
* @removed use
* {@link #onTranslationRequest(TranslationRequest, int, CancellationSignal, Consumer)} instead.
*/
@@ -276,23 +274,29 @@
* {@link TranslationRequest#FLAG_PARTIAL_RESPONSES} was set, the service may call
* {@code callback.accept()} multiple times with partial responses.</p>
*
- * @param request
- * @param sessionId
- * @param callback
- * @param cancellationSignal
+ * @param request The translation request containing the data to be translated.
+ * @param sessionId id of the session that sent the translation request.
+ * @param cancellationSignal A {@link CancellationSignal} that notifies when a client has
+ * cancelled the operation in progress.
+ * @param callback {@link Consumer} to pass back the translation response.
*/
public abstract void onTranslationRequest(@NonNull TranslationRequest request, int sessionId,
@Nullable CancellationSignal cancellationSignal,
@NonNull Consumer<TranslationResponse> callback);
/**
- * TODO: fill in javadoc
+ * Called to request a set of {@link TranslationCapability}s that are supported by the service.
+ *
+ * <p>The set of translation capabilities are limited to those supporting the source and target
+ * {@link TranslationSpec.DataFormat}. e.g. Calling this with
+ * {@link TranslationSpec#DATA_FORMAT_TEXT} as source and target returns only capabilities that
+ * translates text to text.</p>
*
* <p>Must call {@code callback.accept} to pass back the set of translation capabilities.</p>
*
- * @param sourceFormat
- * @param targetFormat
- * @param callback
+ * @param sourceFormat data format restriction of the translation source spec.
+ * @param targetFormat data format restriction of the translation target spec.
+ * @param callback {@link Consumer} to pass back the set of translation capabilities.
*/
public abstract void onTranslationCapabilitiesRequest(
@TranslationSpec.DataFormat int sourceFormat,
diff --git a/core/java/android/view/translation/TranslationCapability.java b/core/java/android/view/translation/TranslationCapability.java
index 65b749a..b7e13dd 100644
--- a/core/java/android/view/translation/TranslationCapability.java
+++ b/core/java/android/view/translation/TranslationCapability.java
@@ -40,15 +40,18 @@
public final class TranslationCapability implements Parcelable {
/**
- * TODO: fill in javadoc
+ * The translation service supports translation between the source and target specs, and it is
+ * ready to be downloaded onto the device.
*/
public static final @ModelState int STATE_AVAILABLE_TO_DOWNLOAD = 1;
/**
- * TODO: fill in javadoc
+ * The translation service supports translation between the source and target specs, and it is
+ * being downloaded onto the device currently.
*/
public static final @ModelState int STATE_DOWNLOADING = 2;
/**
- * TODO: fill in javadoc
+ * The translation service supports translation between the source and target specs, and it is
+ * downloaded and ready to use on device.
*/
public static final @ModelState int STATE_ON_DEVICE = 3;
/**
@@ -305,7 +308,7 @@
};
@DataClass.Generated(
- time = 1624307114468L,
+ time = 1629158466039L,
codegenVersion = "1.0.23",
sourceFile = "frameworks/base/core/java/android/view/translation/TranslationCapability.java",
inputSignatures = "public static final @android.view.translation.TranslationCapability.ModelState int STATE_AVAILABLE_TO_DOWNLOAD\npublic static final @android.view.translation.TranslationCapability.ModelState int STATE_DOWNLOADING\npublic static final @android.view.translation.TranslationCapability.ModelState int STATE_ON_DEVICE\npublic static final @android.view.translation.TranslationCapability.ModelState int STATE_NOT_AVAILABLE\npublic static final @android.view.translation.TranslationCapability.ModelState int STATE_REMOVED_AND_AVAILABLE\nprivate final @android.view.translation.TranslationCapability.ModelState int mState\nprivate final @android.annotation.NonNull android.view.translation.TranslationSpec mSourceSpec\nprivate final @android.annotation.NonNull android.view.translation.TranslationSpec mTargetSpec\nprivate final boolean mUiTranslationEnabled\nprivate final @android.view.translation.TranslationContext.TranslationFlag int mSupportedTranslationFlags\nclass TranslationCapability extends java.lang.Object implements [android.os.Parcelable]\n@com.android.internal.util.DataClass(genHiddenConstDefs=true, genToString=true, genConstructor=false)")
diff --git a/core/java/android/view/translation/TranslationRequest.java b/core/java/android/view/translation/TranslationRequest.java
index df4836e..0d41851 100644
--- a/core/java/android/view/translation/TranslationRequest.java
+++ b/core/java/android/view/translation/TranslationRequest.java
@@ -39,12 +39,16 @@
public static final @RequestFlags int FLAG_TRANSLATION_RESULT = 0x1;
/**
* Indicates this request wants to receive the dictionary result.
- * TODO: describe the structure of the result.
+ *
+ * <p>See {@link TranslationResponseValue#EXTRA_DEFINITIONS} for more detail on the structure
+ * of the returned data.
*/
public static final @RequestFlags int FLAG_DICTIONARY_RESULT = 0x2;
/**
* Indicates this request wants to receive the transliteration result.
- * TODO: describe the structure of the result.
+ *
+ * <p>This returns a CharSequence representation of the transliteration of the translated text.
+ * See {@link TranslationResponseValue#getTransliteration()}.
*/
public static final @RequestFlags int FLAG_TRANSLITERATION_RESULT = 0x4;
/**
@@ -327,7 +331,8 @@
return this;
}
- /** @see #setTranslationRequestValues
+ /**
+ * @see #setTranslationRequestValues
* @removed
*/
@DataClass.Generated.Member
@@ -352,7 +357,8 @@
return this;
}
- /** @see #setViewTranslationRequests
+ /**
+ * @see #setViewTranslationRequests
* @removed
*/
@DataClass.Generated.Member
@@ -394,7 +400,7 @@
}
@DataClass.Generated(
- time = 1620429997487L,
+ time = 1629159107226L,
codegenVersion = "1.0.23",
sourceFile = "frameworks/base/core/java/android/view/translation/TranslationRequest.java",
inputSignatures = "public static final @android.view.translation.TranslationRequest.RequestFlags int FLAG_TRANSLATION_RESULT\npublic static final @android.view.translation.TranslationRequest.RequestFlags int FLAG_DICTIONARY_RESULT\npublic static final @android.view.translation.TranslationRequest.RequestFlags int FLAG_TRANSLITERATION_RESULT\npublic static final @android.view.translation.TranslationRequest.RequestFlags int FLAG_PARTIAL_RESPONSES\nprivate final @android.view.translation.TranslationRequest.RequestFlags int mFlags\nprivate final @android.annotation.NonNull @com.android.internal.util.DataClass.PluralOf(\"translationRequestValue\") java.util.List<android.view.translation.TranslationRequestValue> mTranslationRequestValues\nprivate final @android.annotation.NonNull @com.android.internal.util.DataClass.PluralOf(\"viewTranslationRequest\") java.util.List<android.view.translation.ViewTranslationRequest> mViewTranslationRequests\nprivate static int defaultFlags()\nprivate static java.util.List<android.view.translation.TranslationRequestValue> defaultTranslationRequestValues()\nprivate static java.util.List<android.view.translation.ViewTranslationRequest> defaultViewTranslationRequests()\nclass TranslationRequest extends java.lang.Object implements [android.os.Parcelable]\npublic abstract @java.lang.Deprecated android.view.translation.TranslationRequest.Builder addTranslationRequestValue(android.view.translation.TranslationRequestValue)\npublic abstract @java.lang.Deprecated android.view.translation.TranslationRequest.Builder addViewTranslationRequest(android.view.translation.ViewTranslationRequest)\nclass BaseBuilder extends java.lang.Object implements []\n@com.android.internal.util.DataClass(genToString=true, genHiddenConstDefs=true, genBuilder=true)\npublic abstract @java.lang.Deprecated android.view.translation.TranslationRequest.Builder addTranslationRequestValue(android.view.translation.TranslationRequestValue)\npublic abstract @java.lang.Deprecated android.view.translation.TranslationRequest.Builder addViewTranslationRequest(android.view.translation.ViewTranslationRequest)\nclass BaseBuilder extends java.lang.Object implements []")
diff --git a/core/java/android/view/translation/TranslationResponseValue.java b/core/java/android/view/translation/TranslationResponseValue.java
index a24dbc3..9dff2d5 100644
--- a/core/java/android/view/translation/TranslationResponseValue.java
+++ b/core/java/android/view/translation/TranslationResponseValue.java
@@ -93,9 +93,11 @@
@NonNull
private final Bundle mExtras;
+ // TODO: Add example of transliteration.
/**
* The transliteration result of the translated text.
- * TODO: Describe the result structure.
+ *
+ * <p>This returns a CharSequence representation of the transliteration of the translated text.
*/
@Nullable
private final CharSequence mTransliteration;
@@ -223,7 +225,8 @@
/**
* The transliteration result of the translated text.
- * TODO: Describe the result structure.
+ *
+ * <p>This returns a CharSequence representation of the transliteration of the translated text.
*/
@DataClass.Generated.Member
public @Nullable CharSequence getTransliteration() {
@@ -407,7 +410,8 @@
/**
* The transliteration result of the translated text.
- * TODO: Describe the result structure.
+ *
+ * <p>This returns a CharSequence representation of the transliteration of the translated text.
*/
@DataClass.Generated.Member
public @NonNull Builder setTransliteration(@NonNull CharSequence value) {
@@ -448,7 +452,7 @@
}
@DataClass.Generated(
- time = 1622133051937L,
+ time = 1631057245846L,
codegenVersion = "1.0.23",
sourceFile = "frameworks/base/core/java/android/view/translation/TranslationResponseValue.java",
inputSignatures = "public static final int STATUS_SUCCESS\npublic static final int STATUS_ERROR\npublic static final java.lang.String EXTRA_DEFINITIONS\nprivate final @android.view.translation.TranslationResponseValue.Status int mStatusCode\nprivate final @android.annotation.Nullable java.lang.CharSequence mText\nprivate final @android.annotation.NonNull android.os.Bundle mExtras\nprivate final @android.annotation.Nullable java.lang.CharSequence mTransliteration\npublic static @android.annotation.NonNull android.view.translation.TranslationResponseValue forError()\nprivate static java.lang.CharSequence defaultText()\nprivate static android.os.Bundle defaultExtras()\nprivate boolean extrasEquals(android.os.Bundle)\nprivate static java.lang.CharSequence defaultTransliteration()\nclass TranslationResponseValue extends java.lang.Object implements [android.os.Parcelable]\nclass BaseBuilder extends java.lang.Object implements []\n@com.android.internal.util.DataClass(genBuilder=true, genToString=true, genEqualsHashCode=true, genHiddenConstDefs=true)\nclass BaseBuilder extends java.lang.Object implements []")
