Improve Javadoc for USB Manager and MTP/PTP support.

Bug: 4091519

Change-Id: Ida79593d5a984f7ffd0934ae7bded23b8faf9eef
Signed-off-by: Mike Lockwood <lockwood@android.com>

2 files changed, 31 insertions, 10 deletions

diff --git a/media/java/android/mtp/MtpDevice.java b/media/java/android/mtp/MtpDevice.java
index af37c9e..47bb8c9 100644
--- a/media/java/android/mtp/MtpDevice.java
+++ b/media/java/android/mtp/MtpDevice.java
@@ -61,7 +61,9 @@ public final class MtpDevice {
     }
 
     /**
-     * Closes all resources related to the MtpDevice object
+     * Closes all resources related to the MtpDevice object.
+     * After this is called, the object can not be used until {@link #open} is called again
+     * with a new {@link android.hardware.usb.UsbDeviceConnection}.
      */
     public void close() {
         native_close();
@@ -78,6 +80,8 @@ public final class MtpDevice {
 
     /**
      * Returns the name of the USB device
+     * This returns the same value as {@link android.hardware.usb.UsbDevice#getDeviceName}
+     * for the device's {@link android.hardware.usb.UsbDevice}
      *
      * @return the device name
      */
@@ -86,7 +90,9 @@ public final class MtpDevice {
     }
 
     /**
-     * Returns the ID of the USB device
+     * Returns the USB ID of the USB device.
+     * This returns the same value as {@link android.hardware.usb.UsbDevice#getDeviceId}
+     * for the device's {@link android.hardware.usb.UsbDevice}
      *
      * @return the device ID
      */
@@ -100,7 +106,7 @@ public final class MtpDevice {
     }
 
     /**
-     * Returns the {@link android.mtp.MtpDeviceInfo} for this device
+     * Returns the {@link MtpDeviceInfo} for this device
      *
      * @return the device info
      */
@@ -110,8 +116,9 @@ public final class MtpDevice {
 
     /**
      * Returns the list of IDs for all storage units on this device
+     * Information about each storage unit can be accessed via {@link #getStorageInfo}.
      *
-     * @return the storage IDs
+     * @return the list of storage IDs
      */
     public int[] getStorageIds() {
         return native_get_storage_ids();
@@ -120,6 +127,7 @@ public final class MtpDevice {
     /**
      * Returns the list of object handles for all objects on the given storage unit,
      * with the given format and parent.
+     * Information about each object can be accessed via {@link #getObjectInfo}.
      *
      * @param storageId the storage unit to query
      * @param format the format of the object to return, or zero for all formats
@@ -132,10 +140,12 @@ public final class MtpDevice {
 
     /**
      * Returns the data for an object as a byte array.
+     * This call may block for an arbitrary amount of time depending on the size
+     * of the data and speed of the devices.
      *
      * @param objectHandle handle of the object to read
      * @param objectSize the size of the object (this should match
-     *      {@link android.mtp.MtpObjectInfo#getCompressedSize}
+     *      {@link MtpObjectInfo#getCompressedSize}
      * @return the object's data, or null if reading fails
      */
     public byte[] getObject(int objectHandle, int objectSize) {
@@ -144,6 +154,10 @@ public final class MtpDevice {
 
     /**
      * Returns the thumbnail data for an object as a byte array.
+     * The size and format of the thumbnail data can be determined via
+     * {@link MtpObjectInfo#getThumbCompressedSize} and
+     * {@link MtpObjectInfo#getThumbFormat}.
+     * For typical devices the format is JPEG.
      *
      * @param objectHandle handle of the object to read
      * @return the object's thumbnail, or null if reading fails
@@ -153,7 +167,7 @@ public final class MtpDevice {
     }
 
     /**
-     * Retrieves the {@link android.mtp.MtpStorageInfo} for a storage unit.
+     * Retrieves the {@link MtpStorageInfo} for a storage unit.
      *
      * @param storageId the ID of the storage unit
      * @return the MtpStorageInfo
@@ -163,7 +177,7 @@ public final class MtpDevice {
     }
 
     /**
-     * Retrieves the {@link android.mtp.MtpObjectInfo} for an object.
+     * Retrieves the {@link MtpObjectInfo} for an object.
      *
      * @param objectHandle the handle of the object
      * @return the MtpObjectInfo
@@ -173,7 +187,9 @@ public final class MtpDevice {
     }
 
     /**
-     * Deletes an object on the device.
+     * Deletes an object on the device.  This call may block, since
+     * deleting a directory containing many files may take a long time
+     * on some devices.
      *
      * @param objectHandle handle of the object to delete
      * @return true if the deletion succeeds
@@ -204,6 +220,8 @@ public final class MtpDevice {
 
     /**
      * Copies the data for an object to a file in external storage.
+     * This call may block for an arbitrary amount of time depending on the size
+     * of the data and speed of the devices.
      *
      * @param objectHandle handle of the object to read
      * @param destPath path to destination for the file transfer.
diff --git a/media/java/android/mtp/MtpStorageInfo.java b/media/java/android/mtp/MtpStorageInfo.java
index 09736a8..d1b86fc 100644
--- a/media/java/android/mtp/MtpStorageInfo.java
+++ b/media/java/android/mtp/MtpStorageInfo.java
@@ -34,7 +34,8 @@ public final class MtpStorageInfo {
     }
 
     /**
-     * Returns the storage ID for the storage unit
+     * Returns the storage ID for the storage unit.
+     * The storage ID uniquely identifies the storage unit on the MTP device.
      *
      * @return the storage ID
      */
@@ -61,7 +62,9 @@ public final class MtpStorageInfo {
     }
 
    /**
-     * Returns the description string for the storage unit
+     * Returns the description string for the storage unit.
+     * This is typically displayed to the user in the user interface on the
+     * MTP host.
      *
      * @return the storage unit description
      */