Comment-only change to add documentation for FileObserver

Change-Id: Icd9bc65be020a23f78c8bcda78fc68e7d05c93b4

Author: egnor

core/java/android/os/FileObserver.java

@@ -24,33 +24,52 @@
 import java.util.ArrayList;
 import java.util.HashMap;
 
+/**
+ * Monitors files (using <a href="http://en.wikipedia.org/wiki/Inotify">inotify</a>)
+ * to fire an event after files are accessed or changed by by any process on
+ * the device (including this one).  FileObserver is an abstract class;
+ * subclasses must implement the event handler {@link #onEvent(int, String)}.
+ *
+ * <p>Each FileObserver instance monitors a single file or directory.
+ * If a directory is monitored, events will be triggered for all files and
+ * subdirectories (recursively) inside the monitored directory.</p>
+ *
+ * <p>An event mask is used to specify which changes or actions to report.
+ * Event type constants are used to describe the possible changes in the
+ * event mask as well as what actually happened in event callbacks.</p>
+ *
+ * <p class="caution"><b>Warning</b>: If a FileObserver is garbage collected, it
+ * will stop sending events.  To ensure you keep receiving events, you must
+ * keep a reference to the FileObserver instance from some other live object.</p>
+ */
 public abstract class FileObserver {
-    /** File was accessed */
+    /** Event type: Data was read from a file */
     public static final int ACCESS = 0x00000001;
-    /** File was modified */
+    /** Event type: Data was written to a file */
     public static final int MODIFY = 0x00000002;
-    /** Metadata changed */
+    /** Event type: Metadata (permissions, owner, timestamp) was changed explicitly */
     public static final int ATTRIB = 0x00000004;
-    /** Writable file was closed */
+    /** Event type: Someone had a file or directory open for writing, and closed it */
     public static final int CLOSE_WRITE = 0x00000008;
-    /** Unwrittable file closed */
+    /** Event type: Someone had a file or directory open read-only, and closed it */
     public static final int CLOSE_NOWRITE = 0x00000010;
-    /** File was opened */
+    /** Event type: A file or directory was opened */
     public static final int OPEN = 0x00000020;
-    /** File was moved from X */
+    /** Event type: A file or subdirectory was moved from the monitored directory */
     public static final int MOVED_FROM = 0x00000040;
-    /** File was moved to Y */
+    /** Event type: A file or subdirectory was moved to the monitored directory */
     public static final int MOVED_TO = 0x00000080;
-    /** Subfile was created */
+    /** Event type: A new file or subdirectory was created under the monitored directory */
     public static final int CREATE = 0x00000100;
-    /** Subfile was deleted */
+    /** Event type: A file was deleted from the monitored directory */
     public static final int DELETE = 0x00000200;
-    /** Self was deleted */
+    /** Event type: The monitored file or directory was deleted; monitoring effectively stops */
     public static final int DELETE_SELF = 0x00000400;
-    /** Self was moved */
+    /** Event type: The monitored file or directory was moved; monitoring continues */
     public static final int MOVE_SELF = 0x00000800;
 
-    public static final int ALL_EVENTS = ACCESS | MODIFY | ATTRIB | CLOSE_WRITE 
+    /** Event mask: All valid event types, combined */
+    public static final int ALL_EVENTS = ACCESS | MODIFY | ATTRIB | CLOSE_WRITE
             | CLOSE_NOWRITE | OPEN | MOVED_FROM | MOVED_TO | DELETE | CREATE
             | DELETE_SELF | MOVE_SELF;
 
@@ -128,10 +147,21 @@ public void onEvent(int wfd, int mask, String path) {
     private Integer m_descriptor;
     private int m_mask;
 
+    /**
+     * Equivalent to FileObserver(path, FileObserver.ALL_EVENTS).
+     */
     public FileObserver(String path) {
         this(path, ALL_EVENTS);
     }
 
+    /**
+     * Create a new file observer for a certain file or directory.
+     * Monitoring does not start on creation!  You must call
+     * {@link #startWatching()} before you will receive events.
+     *
+     * @param path The file or directory to monitor
+     * @param mask The event or events (added together) to watch for
+     */
     public FileObserver(String path, int mask) {
         m_path = path;
         m_mask = mask;
@@ -142,18 +172,42 @@ protected void finalize() {
         stopWatching();
     }
 
+    /**
+     * Start watching for events.  The monitored file or directory must exist at
+     * this time, or else no events will be reported (even if it appears later).
+     * If monitoring is already started, this call has no effect.
+     */
     public void startWatching() {
         if (m_descriptor < 0) {
             m_descriptor = s_observerThread.startWatching(m_path, m_mask, this);
         }
     }
 
+    /**
+     * Stop watching for events.  Some events may be in process, so events
+     * may continue to be reported even after this method completes.  If
+     * monitoring is already stopped, this call has no effect.
+     */
     public void stopWatching() {
         if (m_descriptor >= 0) {
             s_observerThread.stopWatching(m_descriptor);
             m_descriptor = -1;
         }
     }
 
+    /**
+     * The event handler, which must be implemented by subclasses.
+     *
+     * <p class="note">This method is invoked on a special FileObserver thread.
+     * It runs independently of any threads, so take care to use appropriate
+     * synchronization!  Consider using {@link Handler#post(Runnable)} to shift
+     * event handling work to the main thread to avoid concurrency problems.</p>
+     *
+     * <p>Event handlers must not throw exceptions.</p>
+     *
+     * @param event The type of event which happened
+     * @param path The path, relative to the main monitored file or directory,
+     *     of the file or directory which triggered the event
+     */
     public abstract void onEvent(int event, String path);
 }