Update the documentaton of the android.print package.
bug:10551786
bug:10551697
bug:10705082
bug:10741641
bug:11318976
bug:10550979
bug:10551761
Change-Id: I46ceb66a69b6d32d6b417356178f67f2e25e891a
diff --git a/core/java/android/print/PrinterCapabilitiesInfo.java b/core/java/android/print/PrinterCapabilitiesInfo.java
index df51ec1..b615600 100644
--- a/core/java/android/print/PrinterCapabilitiesInfo.java
+++ b/core/java/android/print/PrinterCapabilitiesInfo.java
@@ -24,10 +24,17 @@
import java.util.ArrayList;
import java.util.Arrays;
+import java.util.Collections;
import java.util.List;
/**
- * This class represents the capabilities of a printer.
+ * This class represents the capabilities of a printer. Instances
+ * of this class are created by a print service to report the
+ * capabilities of a printer it manages. The capabilities of a
+ * printer specify how it can print content. For example, what
+ * are the media sizes supported by the printer, what are the
+ * minimal margins of the printer based on its technical design,
+ * etc.
*/
public final class PrinterCapabilitiesInfo implements Parcelable {
/**
@@ -112,7 +119,7 @@
* @return The media sizes.
*/
public List<MediaSize> getMediaSizes() {
- return mMediaSizes;
+ return Collections.unmodifiableList(mMediaSizes);
}
/**
@@ -121,7 +128,7 @@
* @return The resolutions.
*/
public List<Resolution> getResolutions() {
- return mResolutions;
+ return Collections.unmodifiableList(mResolutions);
}
/**
@@ -135,9 +142,9 @@
}
/**
- * Gets the supported color modes.
+ * Gets the bit mask of supported color modes.
*
- * @return The color modes.
+ * @return The bit mask of supported color modes.
*
* @see PrintAttributes#COLOR_MODE_COLOR
* @see PrintAttributes#COLOR_MODE_MONOCHROME
@@ -355,9 +362,10 @@
}
/**
- * Builder for creating of a {@link PrinterInfo}. This class is responsible
- * to enforce that all required attributes have at least one default value.
- * In other words, this class creates only well-formed {@link PrinterInfo}s.
+ * Builder for creating of a {@link PrinterCapabilitiesInfo}. This class is
+ * responsible to enforce that all required attributes have at least one
+ * default value. In other words, this class creates only well-formed {@link
+ * PrinterCapabilitiesInfo}s.
* <p>
* Look at the individual methods for a reference whether a property is
* required or if it is optional.
@@ -369,9 +377,9 @@
/**
* Creates a new instance.
*
- * @param printerId The printer id. Cannot be null.
+ * @param printerId The printer id. Cannot be <code>null</code>.
*
- * @throws IllegalArgumentException If the printer id is null.
+ * @throws IllegalArgumentException If the printer id is <code>null</code>.
*/
public Builder(PrinterId printerId) {
if (printerId == null) {
@@ -492,7 +500,7 @@
/**
* Crates a new {@link PrinterCapabilitiesInfo} enforcing that all
- * required properties have need specified. See individual methods
+ * required properties have been specified. See individual methods
* in this class for reference about required attributes.
*
* @return A new {@link PrinterCapabilitiesInfo}.
@@ -521,7 +529,7 @@
if (mPrototype.mMinMargins == null) {
throw new IllegalArgumentException("margins cannot be null");
}
- return new PrinterCapabilitiesInfo(mPrototype);
+ return mPrototype;
}
private void throwIfDefaultAlreadySpecified(int propertyIndex) {