Document the fact that StatFs.restat() and ctor can throw.

StatFs.restat() and the StatFs constructor can throw
IllegalArgumentException. This was not previously documented;
not all callers took this into account, for example:
   http://r.android.com/251290

This CL adds documentation to those methods. It also adds
comments to two of the callers.

Separately from this CL, we may in addition consider adding
new API StatFs.checkedRestat() and StatFs.checkedCreate()
or similar that throw IOException; we cannot change the
existing constructor and method since they are public.

Test: Checked that "make" still completed successfully.

Change-Id: I6a0b3cb7718939408937c61de7c3b000b948fa59

core/java/android/database/sqlite/SQLiteGlobal.java

@@ -61,6 +61,8 @@ public final class SQLiteGlobal {
     public static int getDefaultPageSize() {
         synchronized (sLock) {
             if (sDefaultPageSize == 0) {
+                // If there is an issue accessing /data, something is so seriously
+                // wrong that we just let the IllegalArgumentException propagate.
                 sDefaultPageSize = new StatFs("/data").getBlockSize();
             }
             return SystemProperties.getInt("debug.sqlite.pagesize", sDefaultPageSize);

core/java/android/os/StatFs.java

@@ -34,11 +34,16 @@ public class StatFs {
      * class.
      *
      * @param path path in the desired file system to stat.
+     *
+     * @throws IllegalArgumentException if the file system access fails
      */
     public StatFs(String path) {
         mStat = doStat(path);
     }
 
+    /**
+     * @throws IllegalArgumentException if the file system access fails
+     */
     private static StructStatVfs doStat(String path) {
         try {
             return Os.statvfs(path);
@@ -51,6 +56,8 @@ public class StatFs {
      * Perform a restat of the file system referenced by this object. This is
      * the same as re-constructing the object with the same file system path,
      * and the new stat values are available upon return.
+     *
+     * @throws IllegalArgumentException if the file system access fails
      */
     public void restat(String path) {
         mStat = doStat(path);

services/core/java/com/android/server/storage/DeviceStorageMonitorService.java

@@ -330,7 +330,8 @@ public class DeviceStorageMonitorService extends SystemService {
         mLastReportedFreeMemTime = 0;
         mResolver = context.getContentResolver();
         mIsBootImageOnDisk = isBootImageOnDisk();
-        //create StatFs object
+        // If these constructors throw IllegalArgumentException, something
+        // is so seriously wrong that we just let the Exception propagate.
         mDataFileStats = new StatFs(DATA_PATH.getAbsolutePath());
         mSystemFileStats = new StatFs(SYSTEM_PATH.getAbsolutePath());
         mCacheFileStats = new StatFs(CACHE_PATH.getAbsolutePath());