Improve comments

Author: sungshik

src/main/java/engineering/swat/watch/impl/mac/NativeEventHandler.java

@@ -33,19 +33,20 @@
 
 /**
  * <p>
- * Handler for native events, intended to be used for the construction of
- * JDK's {@link WatchEvent}s (and continue downstream consumption).
+ * Handler for native events, intended to be used in a {@link NativeEventStream}
+ * callback to construct {@link WatchEvent}s (and propagate them for downstream
+ * consumption).
  * </p>
  *
  * <p>
- * In each call, the types of {@code kind} and {@code context} depend
+ * In each invocation, the types of {@code kind} and {@code context} depend
  * specifically on the given native event: they're {@code Kind<Path>} and
  * {@code Path} for non-overflows, but they're {@code Kind<Object>} and
  * {@code Object} for overflows. This precision is needed to construct
- * {@link WatchEvent}s, where the types of {@code kind} and {@code context}
- * are correlated. Note: {@link java.util.function.BiConsumer} doesn't give
- * the required precision (i.e., its type parameters are initialized only
- * once for all calls).
+ * {@link WatchEvent}s, where the types of {@code kind} and {@code context} need
+ * to be correlated. Note: {@link java.util.function.BiConsumer} doesn't give
+ * the required precision (i.e., its type parameters are initialized only once
+ * for all invocations).
  * </p>
  */
 @FunctionalInterface

src/main/java/engineering/swat/watch/impl/mac/NativeEventStream.java

@@ -59,19 +59,20 @@
 import engineering.swat.watch.impl.mac.apis.FileSystemEvents.FSEventStreamCallback;
 
 // Note: This file is designed to be the only place in this package where JNA is
-// used and/or the native APIs are called. If the need to do so arises outside
+// used and/or the native APIs are invoked. If the need to do so arises outside
 // this file, consider extending this file to offer the required services
 // without exposing JNA and/or the native APIs.
 
 /**
  * <p>
- * Stream of native events for a path, issued by macOS.
+ * Stream of native events for a path, issued by macOS. It's a facade-like
+ * object that hides the low-level native APIs behind a higher-level interface.
  * </p>
  *
  * <p>
  * Note: Methods {@link #open()} and {@link #close()} synchronize on this object
  * to avoid races. The synchronization overhead is expected to be negligible, as
- * these methods are expected to be rarely called.
+ * these methods are expected to be rarely invoked.
  * </p>
  */
 public class NativeEventStream implements Closeable {

src/test/java/engineering/swat/watch/impl/mac/APIs.java

@@ -107,7 +107,7 @@ void smokeTest() throws IOException {
     }
 
     public static void main(String[] args) throws IOException {
-        var s = "/Users/sungshik/Desktop/tmp";
+        var s = args[0];
         var handler = (MinimalWorkingExample.EventHandler) (path, flags, id) -> {
             LOGGER.info(prettyPrint(path, flags, id));
         };
@@ -130,9 +130,9 @@ private static String prettyPrint(String path, int flags, long id) {
     }
 
     private static class MinimalWorkingExample implements Closeable {
-        FileSystemEvents.FSEventStreamCallback callback;
-        Pointer stream;
-        Pointer queue;
+        private FileSystemEvents.FSEventStreamCallback callback;
+        private Pointer stream;
+        private Pointer queue;
 
         public MinimalWorkingExample(String s, EventHandler handler) {