clean: Add missing JavaDoc (by Google Jules)

Author: google-labs-jules[bot]

src/main/java/ch/vorburger/fswatch/DirectoryWatcher.java

@@ -29,8 +29,19 @@
  */
 public interface DirectoryWatcher extends Closeable {
 
+    /**
+     * The kind of change that occurred.
+     */
     enum ChangeKind {
-        MODIFIED, DELETED, CREATED
+
+        /** Directory or file was modified. */
+        MODIFIED,
+
+        /** Directory or file was deleted. */
+        DELETED,
+
+        /** Directory or file was created. */
+        CREATED
     }
 
     /**
@@ -50,10 +61,16 @@ interface Listener {
      * Handles exceptions which occur during Listener onChange().
      */
     interface ExceptionHandler {
+        /**
+         * Called when an exception occurs.
+         * @param t the exception
+         */
         void onException(Throwable t);
     }
 
-    @Override String toString();
+    @Override
+    String toString();
 
-    @Override void close(); // do NOT throws (IO)Exception
+    @Override
+    void close(); // do NOT throws (IO)Exception
 }

src/main/java/ch/vorburger/fswatch/DirectoryWatcherBuilder.java

@@ -50,10 +50,20 @@ public class DirectoryWatcherBuilder {
     protected ChangeKind[] eventKinds = { ChangeKind.DELETED, ChangeKind.MODIFIED };
     protected boolean existingFiles = false;
 
+    /**
+     * Set the path to watch.
+     * @param directory the path to watch
+     * @return this
+     */
     public DirectoryWatcherBuilder path(File directory) {
         return path(directory.toPath());
     }
 
+    /**
+     * Set the path to watch.
+     * @param directory the path to watch
+     * @return this
+     */
     public DirectoryWatcherBuilder path(Path directory) {
         if (path != null) {
             throw new IllegalStateException("path already set");
@@ -62,6 +72,11 @@ public DirectoryWatcherBuilder path(Path directory) {
         return this;
     }
 
+    /**
+     * Set the listener to be notified of changes.
+     * @param listener the listener to be notified of changes
+     * @return this
+     */
     public DirectoryWatcherBuilder listener(Listener listener) {
         if (this.listener != null) {
             throw new IllegalStateException("listener already set");
@@ -70,16 +85,31 @@ public DirectoryWatcherBuilder listener(Listener listener) {
         return this;
     }
 
+    /**
+     * Set the change kinds to listen for.
+     * @param eventKinds the change kinds to listen for
+     * @return this
+     */
     public DirectoryWatcherBuilder eventKinds(ChangeKind... eventKinds) {
         this.eventKinds = eventKinds;
         return this;
     }
 
+    /**
+     * Set the exception handler.
+     * @param exceptionHandler the exception handler
+     * @return this
+     */
     public DirectoryWatcherBuilder exceptionHandler(ExceptionHandler exceptionHandler) {
         this.exceptionHandler = requireNonNull(exceptionHandler);
         return this;
     }
 
+    /**
+     * Set the quiet period in milliseconds.
+     * @param quietPeriodInMS the quiet period in milliseconds
+     * @return this
+     */
     public DirectoryWatcherBuilder quietPeriodInMS(long quietPeriodInMS) {
         this.quietPeriodInMS = quietPeriodInMS;
         return this;

src/main/java/ch/vorburger/fswatch/DirectoryWatcherImpl.java

@@ -51,7 +51,7 @@
  * @author Michael Vorburger.ch
  */
 // intentionally package local, for now
-public class DirectoryWatcherImpl implements DirectoryWatcher {
+class DirectoryWatcherImpl implements DirectoryWatcher {
     private final static Logger log = LoggerFactory.getLogger(DirectoryWatcherImpl.class);
 
     protected final WatchService watcher = FileSystems.getDefault().newWatchService(); // better final, as it will be accessed by both threads (normally OK either way, but still)

src/main/java/ch/vorburger/fswatch/DirectoryWatcherMain.java

@@ -32,6 +32,12 @@
  */
 public class DirectoryWatcherMain {
 
+    /**
+     * Main method.
+     * @param args command line arguments
+     * @throws IOException if an I/O error occurs
+     * @throws InterruptedException if the thread is interrupted
+     */
     public static void main(String[] args) throws IOException, InterruptedException {
         if (args.length < 1) {
             System.err.println("USAGE: <root-directory-to-watch-for-changes>");

src/main/java/ch/vorburger/fswatch/FileWatcherBuilder.java

@@ -33,11 +33,21 @@
  */
 public class FileWatcherBuilder extends DirectoryWatcherBuilder {
 
+    /**
+     * Set the path to watch.
+     * @param fileNotDirectory the path to watch
+     * @return this
+     */
     @Override
     public FileWatcherBuilder path(File fileNotDirectory) {
         return (FileWatcherBuilder) super.path(fileNotDirectory.getAbsoluteFile());
     }
 
+    /**
+     * Set the path to watch.
+     * @param fileNotDirectory the path to watch
+     * @return this
+     */
     @Override
     public FileWatcherBuilder path(Path fileNotDirectory) {
         return (FileWatcherBuilder) super.path(fileNotDirectory.toAbsolutePath());
@@ -57,9 +67,11 @@ public DirectoryWatcher build() throws IOException {
                     "When using FileWatcherBuilder, set path() to a single file, not a directory (use DirectoryWatcherBuilder to watch a directory, and it's subdirectories)");
         }
         // NOTE We do want to wrap the FileWatcherListener inside the QuietPeriodListener, and not the other way around!
-        Listener wrap = getQuietListener(new FileWatcherListener(path, listener));
+        Listener fileWatcherListener = new FileWatcherListener(path, listener);
+        Listener wrap = getQuietListener(fileWatcherListener);
         Path parent = path.getParent();
-        if (parent == null) throw new IllegalArgumentException("path does not have a parent: " + path);
+        if (parent == null)
+            throw new IllegalArgumentException("path does not have a parent: " + path);
         DirectoryWatcherImpl watcher = new DirectoryWatcherImpl(false, parent, wrap, fileFilter,
                 exceptionHandler, eventKinds);
         firstListenerNotification();
@@ -74,6 +86,11 @@ protected static class FileWatcherListener implements Listener {
         private final Listener delegate;
         private final Path fileToWatch;
 
+        /**
+         * Constructor.
+         * @param fileToWatch the file to watch
+         * @param listenerToWrap the listener to wrap
+         */
         protected FileWatcherListener(Path fileToWatch, Listener listenerToWrap) {
             this.fileToWatch = fileToWatch;
             delegate = listenerToWrap;

src/main/java/ch/vorburger/fswatch/QuietPeriodListener.java

@@ -40,6 +40,12 @@ public class QuietPeriodListener implements Listener {
     protected @Nullable Thread thread;
     protected volatile boolean sleepAgain;
 
+    /**
+     * Constructor.
+     * @param quietPeriodInMS the quiet period in milliseconds
+     * @param listenerToWrap the listener to wrap
+     * @param exceptionHandler the exception handler
+     */
     public QuietPeriodListener(long quietPeriodInMS, Listener listenerToWrap, ExceptionHandler exceptionHandler) {
         this.quietPeriodInMS = quietPeriodInMS;
         this.delegate = listenerToWrap;

src/main/java/ch/vorburger/fswatch/package-info.java

@@ -17,6 +17,10 @@
  * limitations under the License.
  * #L%
  */
+
+/**
+ * Watch a directory and be notified on your Listener for changes in it.
+ */
 @NullMarked
 package ch.vorburger.fswatch;