1 files changed, 66 insertions, 17 deletions

diff --git a/core/java/android/print/PrintDocumentAdapter.java b/core/java/android/print/PrintDocumentAdapter.java
index 4113ac7..9e811a6 100644
--- a/core/java/android/print/PrintDocumentAdapter.java
+++ b/core/java/android/print/PrintDocumentAdapter.java
@@ -38,15 +38,46 @@ import android.os.ParcelFileDescriptor;
  * </li>
  * <li>
  * After every call to {@link #onLayout(PrintAttributes, PrintAttributes,
- * CancellationSignal, LayoutResultCallback, Bundle)}, you may get a call to
- * {@link #onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal, WriteResultCallback)}
- * asking you to write a PDF file with the content for specific pages.
+ * CancellationSignal, LayoutResultCallback, Bundle)}, you <strong>may</strong> get
+ * a call to {@link #onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal,
+ * WriteResultCallback)} asking you to write a PDF file with the content for
+ * specific pages.
  * </li>
  * <li>
  * Finally, you will receive a call to {@link #onFinish()}. You can use this
  * callback to release resources allocated in {@link #onStart()}.
  * </li>
  * </ul>
+ * <p>
+ * The {@link #onStart()} callback is always the first call you will receive and
+ * is useful for doing one time setup or resource allocation before printing. You
+ * will not receive a subsequent call here.
+ * </p>
+ * <p>
+ * The {@link #onLayout(PrintAttributes, PrintAttributes, CancellationSignal,
+ * LayoutResultCallback, Bundle)} callback requires that you layout the content
+ * based on the current {@link PrintAttributes}. The execution of this method is
+ * not considered completed until you invoke one of the methods on the passed in
+ * callback instance. Hence, you will not receive a subsequent call to any other
+ * method of this class until the execution of this method is complete by invoking
+ * one of the callback methods.
+ * </p>
+ * <p>
+ * The {@link #onWrite(PageRange[], ParcelFileDescriptor, CancellationSignal,
+ * WriteResultCallback)} requires that you render and write the content of some
+ * pages to the provided destination. The execution of this method is not
+ * considered complete until you invoke one of the methods on the passed in
+ * callback instance. Hence, you will not receive a subsequent call to any other
+ * method of this class until the execution of this method is complete by invoking
+ * one of the callback methods. You will never receive a sequence of one or more
+ * calls to this method without a previous call to {@link #onLayout(PrintAttributes,
+ * PrintAttributes, CancellationSignal, LayoutResultCallback, Bundle)}.
+ * </p>
+ * <p>
+ * The {@link #onFinish()} callback is always the last call you will receive and
+ * is useful for doing one time cleanup or resource deallocation after printing.
+ * You will not receive a subsequent call here.
+ * </p>
  * </p>
  * <h3>Implementation</h3>
  * <p>
@@ -54,7 +85,11 @@ import android.os.ParcelFileDescriptor;
  * of the work on an arbitrary thread. For example, if the printed content
  * does not depend on the UI state, i.e. on what is shown on the screen, then
  * you can offload the entire work on a dedicated thread, thus making your
- * application interactive while the print work is being performed.
+ * application interactive while the print work is being performed. Note that
+ * while your activity is covered by the system print UI and a user cannot
+ * interact with it, doing the printing work on the main application thread
+ * may affect the performance of your other application components as they
+ * are also executed on that thread.
  * </p>
  * <p>
  * You can also do work on different threads, for example if you print UI
@@ -64,7 +99,7 @@ import android.os.ParcelFileDescriptor;
  * This will ensure that the UI does not change while you are laying out the
  * printed content. Then you can handle {@link #onWrite(PageRange[], ParcelFileDescriptor,
  * CancellationSignal, WriteResultCallback)} and {@link #onFinish()} on another
- * thread. This will ensure that the UI is frozen for the minimal amount of
+ * thread. This will ensure that the main thread is busy for a minimal amount of
  * time. Also this assumes that you will generate the printed content in
  * {@link #onLayout(PrintAttributes, PrintAttributes, CancellationSignal,
  * LayoutResultCallback, Bundle)} which is not mandatory. If you use multiple
@@ -76,6 +111,12 @@ public abstract class PrintDocumentAdapter {
     /**
      * Extra: mapped to a boolean value that is <code>true</code> if
      * the current layout is for a print preview, <code>false</code> otherwise.
+     * This extra is provided in the {@link Bundle} argument of the {@link
+     * #onLayout(PrintAttributes, PrintAttributes, CancellationSignal,
+     * LayoutResultCallback, Bundle)} callback.
+     *
+     * @see #onLayout(PrintAttributes, PrintAttributes, CancellationSignal,
+     * LayoutResultCallback, Bundle)
      */
     public static final String EXTRA_PRINT_PREVIEW = "EXTRA_PRINT_PREVIEW";
 
@@ -95,17 +136,20 @@ public abstract class PrintDocumentAdapter {
      * After you are done laying out, you <strong>must</strong> invoke: {@link
      * LayoutResultCallback#onLayoutFinished(PrintDocumentInfo, boolean)} with
      * the last argument <code>true</code> or <code>false</code> depending on
-     * whether the layout changed the content or not, respectively; and {@link
-     * LayoutResultCallback#onLayoutFailed(CharSequence)}, if an error occurred.
-     * Note that you must call one of the methods of the given callback.
+     * whether the layout changed the content or not, respectively; or {@link
+     * LayoutResultCallback#onLayoutFailed(CharSequence)}, if an error occurred;
+     * or {@link LayoutResultCallback#onLayoutCancelled()} if layout was
+     * cancelled in a response to a cancellation request via the passed in
+     * {@link CancellationSignal}. Note that you <strong>must</strong> call one of
+     * the methods of the given callback for this method to be considered complete.
      * </p>
      * <p>
      * <strong>Note:</strong> If the content is large and a layout will be
      * performed, it is a good practice to schedule the work on a dedicated
      * thread and register an observer in the provided {@link
      * CancellationSignal} upon invocation of which you should stop the
-     * layout. The cancellation callback will not be made on the main
-     * thread.
+     * layout. The cancellation callback <strong>will not</strong> be made on
+     * the main thread.
      * </p>
      *
      * @param oldAttributes The old print attributes.
@@ -128,10 +172,12 @@ public abstract class PrintDocumentAdapter {
      * on the main thread.
      *<p>
      * After you are done writing, you should close the file descriptor and
-     * invoke {@link WriteResultCallback #onWriteFinished(PageRange[]), if writing
+     * invoke {@link WriteResultCallback#onWriteFinished(PageRange[])}, if writing
      * completed successfully; or {@link WriteResultCallback#onWriteFailed(
-     * CharSequence)}, if an error occurred. Note that you must call one of
-     * the methods of the given callback.
+     * CharSequence)}, if an error occurred; or {@link WriteResultCallback#onWriteCancelled()},
+     * if writing was cancelled in a response to a cancellation request via the passed
+     * in {@link CancellationSignal}. Note that you <strong>must</strong> call one of
+     * the methods of the given callback for this method to be considered complete.
      * </p>
      * <p>
      * <strong>Note:</strong> If the printed content is large, it is a good
@@ -178,7 +224,8 @@ public abstract class PrintDocumentAdapter {
         /**
          * Notifies that all the data was written.
          *
-         * @param pages The pages that were written. Cannot be null or empty.
+         * @param pages The pages that were written. Cannot be <code>null</code>
+         * or empty.
          */
         public void onWriteFinished(PageRange[] pages) {
             /* do nothing - stub */
@@ -187,7 +234,8 @@ public abstract class PrintDocumentAdapter {
         /**
          * Notifies that an error occurred while writing the data.
          *
-         * @param error Error message. May be null if error is unknown.
+         * @param error The <strong>localized</strong> error message.
+         * shown to the user. May be <code>null</code> if error is unknown.
          */
         public void onWriteFailed(CharSequence error) {
             /* do nothing - stub */
@@ -218,7 +266,7 @@ public abstract class PrintDocumentAdapter {
         /**
          * Notifies that the layout finished and whether the content changed.
          *
-         * @param info An info object describing the document. Cannot be null.
+         * @param info An info object describing the document. Cannot be <code>null</code>.
          * @param changed Whether the layout changed.
          *
          * @see PrintDocumentInfo
@@ -230,7 +278,8 @@ public abstract class PrintDocumentAdapter {
         /**
          * Notifies that an error occurred while laying out the document.
          *
-         * @param error Error message. May be null if error is unknown.
+         * @param error The <strong>localized</strong> error message.
+         * shown to the user. May be <code>null</code> if error is unknown.
          */
         public void onLayoutFailed(CharSequence error) {
             /* do nothing - stub */