Fixed javadoc omissions

Author: DavyLandman

.github/workflows/build.yaml

@@ -72,3 +72,5 @@ jobs:
 
       - run: mvn -B editorconfig:check
 
+      - run: mvn -B -Dmaven.javadoc.failOnWarnings javadoc:jar -Prelease
+

pom.xml

@@ -281,6 +281,9 @@
                 </goals>
               </execution>
             </executions>
+            <configuration>
+              <excludePackageNames>engineering.swat.watch.impl:engineering.swat.watch.impl.*</excludePackageNames>
+            </configuration>
           </plugin>
           <plugin> <!-- generate sources jar -->
             <groupId>org.apache.maven.plugins</groupId>

src/main/java/engineering/swat/watch/ActiveWatch.java

@@ -37,12 +37,12 @@
 public interface ActiveWatch extends Closeable {
 
     /**
-     * Gets the path watched by this watch.
+     * @return the path watched by this watch.
      */
     Path getPath();
 
     /**
-     * Gets the scope of this watch.
+     * @return the scope of this watch.
      */
     WatchScope getScope();
 }

src/main/java/engineering/swat/watch/Watch.java

@@ -75,6 +75,7 @@ private Watch(Path path, WatchScope scope) {
      * @param path which absolute path to monitor, can be a file or a directory, but has to be absolute
      * @param scope for directories you can also choose to monitor it's direct children or all it's descendants
      * @throws IllegalArgumentException in case a path is not supported (in relation to the scope)
+     * @return watch builder that can be further configured and then started
      */
     public static Watch build(Path path, WatchScope scope) {
         if (!path.isAbsolute()) {
@@ -103,7 +104,7 @@ public static Watch build(Path path, WatchScope scope) {
      * Use the {@link #withExecutor(Executor)} function to influence the sequencing of these events.
      * By default they can arrive in parallel.
      * @param eventHandler a callback that handles the watch event, will be called once per event.
-     * @return this for optional method chaining
+     * @return {@code this} (to support method chaining)
      */
     public Watch on(Consumer<WatchEvent> eventHandler) {
         if (this.eventHandler != EMPTY_HANDLER) {
@@ -115,6 +116,8 @@ public Watch on(Consumer<WatchEvent> eventHandler) {
 
     /**
      * Convenience variant of {@link #on(Consumer)}, which allows you to only respond to certain events
+     * @param listener gets executed on every event the watch produced
+     * @return {@code this} (to support method chaining)
      */
     public Watch on(WatchEventListener listener) {
         if (this.eventHandler != EMPTY_HANDLER) {

src/main/java/engineering/swat/watch/WatchEvent.java

@@ -71,16 +71,30 @@ public enum Kind {
 
     private static final Path EMPTY_PATH = Path.of("");
 
+    /**
+     * Internal constructor an end user should never call, creates a new watch event for the root of a watch
+     * @param kind kind of watch event
+     * @param rootPath the path of the registered watch
+     */
     public WatchEvent(Kind kind, Path rootPath) {
         this(kind, rootPath, null);
     }
 
+    /**
+     * Internal constructor an end user should never call, creates a new watch event
+     * @param kind kind of watch event
+     * @param rootPath the path of the registered watch
+     * @param relativePath the child path of the event
+     */
     public WatchEvent(Kind kind, Path rootPath, @Nullable Path relativePath) {
         this.kind = kind;
         this.rootPath = rootPath;
         this.relativePath = relativePath == null ? EMPTY_PATH : relativePath;
     }
 
+    /**
+     * @return the kind of watch event
+     */
     public Kind getKind() {
         return this.kind;
     }
@@ -141,6 +155,9 @@ public String toString() {
      * of the same file result in events that are equivalent, but not equal;
      * they need to be distinguishable in collections).
      * </p>
+     * @param e1 event 1
+     * @param e2 event 2
+     * @return true if e1 and e2 are the same path and kind
      */
     public static boolean areEquivalent(WatchEvent e1, WatchEvent e2) {
         return Objects.equals(e1.getKind(), e2.getKind()) &&

src/main/java/engineering/swat/watch/WatchEventListener.java

@@ -30,8 +30,24 @@
  * A visit like interface that allows you to only override the functions you are interested in
  */
 public interface WatchEventListener {
+    /**
+     * executed in case of a create event
+     * @param ev the event
+     */
     default void onCreated(WatchEvent ev) { }
+    /**
+     * executed in case of a modified event
+     * @param ev the event
+     */
     default void onModified(WatchEvent ev) { }
+    /**
+     * executed in case of a delete event
+     * @param ev the event
+     */
     default void onDeleted(WatchEvent ev) { }
+    /**
+     * executed in case of a overflow event
+     * @param ev the event
+     */
     default void onOverflow(WatchEvent ev) { }
 }