1 files changed, 68 insertions, 8 deletions

diff --git a/core/java/android/print/PrintDocumentInfo.java b/core/java/android/print/PrintDocumentInfo.java
index b721ef4..928be6c 100644
--- a/core/java/android/print/PrintDocumentInfo.java
+++ b/core/java/android/print/PrintDocumentInfo.java
@@ -21,12 +21,56 @@ import android.os.Parcelable;
 import android.text.TextUtils;
 
 /**
- * This class encapsulates information about a printed document.
+ * This class encapsulates information about a document for printing
+ * purposes. This meta-data is used by the platform and print services,
+ * components that interact with printers. For example, this class
+ * contains the number of pages contained in the document it describes and
+ * this number of pages is shown to the user allowing him/her to select
+ * the range to print. Also a print service may optimize the printing
+ * process based on the content type, such as document or photo.
+ * <p>
+ * Instances of this class are created by the printing application and
+ * passed to the {@link PrintDocumentAdapter.LayoutResultCallback#onLayoutFinished(
+ * PrintDocumentInfo, boolean) PrintDocumentAdapter.LayoutResultCallback.onLayoutFinished(
+ * PrintDocumentInfo, boolean)} callback after successfully laying out the
+ * content which is performed in {@link PrintDocumentAdapter#onLayout(PrintAttributes,
+ * PrintAttributes, android.os.CancellationSignal, PrintDocumentAdapter.LayoutResultCallback,
+ * android.os.Bundle) PrintDocumentAdapter.onLayout(PrintAttributes,
+ * PrintAttributes, android.os.CancellationSignal,
+ * PrintDocumentAdapter.LayoutResultCallback, android.os.Bundle)}.
+ * </p>
+ * <p>
+ * An example usage looks like this:
+ * <pre>
+ *
+ * . . .
+ *
+ * public void onLayout(PrintAttributes oldAttributes, PrintAttributes newAttributes,
+ *         CancellationSignal cancellationSignal, LayoutResultCallback callback,
+ *         Bundle metadata) {
+ *
+ *        // Assume the app defined a LayoutResult class which contains
+ *        // the layout result data and that the content is a document.
+ *        LayoutResult result = doSomeLayoutWork();
+ *
+ *        PrintDocumentInfo info = new PrintDocumentInfo
+ *                .Builder("printed_file.pdf")
+ *                .setContentType(PrintDocumentInfo.CONTENT_TYPE_DOCUMENT)
+ *                .setPageCount(result.getPageCount())
+ *                .build();
+ *
+ *       callback.onLayoutFinished(info, result.getContentChanged());
+ *   }
+ *
+ *   . . .
+ *
+ * </pre>
+ * </p>
  */
 public final class PrintDocumentInfo implements Parcelable {
 
     /**
-     * Constant for unknown page count..
+     * Constant for unknown page count.
      */
     public static final int PAGE_COUNT_UNKNOWN = -1;
 
@@ -37,11 +81,23 @@ public final class PrintDocumentInfo implements Parcelable {
 
     /**
      * Content type: document.
+     * <p>
+     * A print service may use normal paper to print the content instead
+     * of dedicated photo paper. Also it may use a lower quality printing
+     * process as the content is not as sensitive to print quality variation
+     * as a photo is.
+     * </p>
      */
     public static final int CONTENT_TYPE_DOCUMENT = 0;
 
     /**
      * Content type: photo.
+     * <p>
+     * A print service may use dedicated photo paper to print the content
+     * instead of normal paper. Also it may use a higher quality printing
+     * process as the content is more sensitive to print quality variation
+     * than a document.
+     * </p>
      */
     public static final int CONTENT_TYPE_PHOTO = 1;
 
@@ -82,7 +138,8 @@ public final class PrintDocumentInfo implements Parcelable {
     }
 
     /**
-     * Gets the document name.
+     * Gets the document name. This name may be shown to
+     * the user.
      *
      * @return The document name.
      */
@@ -213,20 +270,23 @@ public final class PrintDocumentInfo implements Parcelable {
     }
 
     /**
-     * Builder for creating an {@link PrintDocumentInfo}.
+     * Builder for creating a {@link PrintDocumentInfo}.
      */
     public static final class Builder {
         private final PrintDocumentInfo mPrototype;
 
         /**
          * Constructor.
+         * 
          * <p>
-         * The values of the relevant properties are initialized with default
-         * values. Please refer to the documentation of the individual setters
-         * for information about the default values.
+         * The values of the relevant properties are initialized with defaults.
+         * Please refer to the documentation of the individual setters for
+         * information about the default values.
          * </p>
          *
-         * @param name The document name. Cannot be empty. 
+         * @param name The document name which may be shown to the user and
+         * is the file name if the content it describes is saved as a PDF.
+         * Cannot be empty. 
          */
         public Builder(String name) {
             if (TextUtils.isEmpty(name)) {