documentation/issue-47: Add missing Javadoc summaries and enable doclint for core

build.gradle

@@ -70,13 +70,6 @@ subprojects {
             testRuntimeOnly(libs.junit.launcher)
         }
     }
-
-    // Suppress javadoc warnings for missing documentation, minor formatting issues.
-    javadoc {
-        options {
-            addStringOption('Xdoclint:none', '-quiet')
-        }
-    }
 }
 
 jreleaser {

core/build.gradle

@@ -7,6 +7,15 @@ description = 'A docking system for JavaFX'
 
 apply from: '../gradle/publishing.gradle'
 
+javadoc {
+    options {
+        // Only the public API exposed in module-info.java; configure Javadoc
+        // to match it.
+        showFromPublic()
+        addBooleanOption('Xdoclint:all,-missing', true)
+    }
+}
+
 javafx {
     version = libs.javafx.base.get().version
     modules = ['javafx.controls']

core/src/main/java/software/coley/bentofx/building/ControlsBuilding.java

@@ -36,6 +36,8 @@ public HeaderPaneFactory getHeaderPaneFactory() {
 	}
 
 	/**
+	 * Sets the factory used to create {@link HeaderPane} instances.
+	 *
 	 * @param headerPaneFactory
 	 * 		Factory for creating {@link HeaderPane}.
 	 *        {@code null} to use the default factory.
@@ -54,6 +56,8 @@ public HeadersFactory getHeadersFactory() {
 	}
 
 	/**
+	 * Sets the factory used to create {@link Headers} instances.
+	 *
 	 * @param headersFactory
 	 * 		Factory for creating {@link Headers}.
 	 *        {@code null} to use the default factory.
@@ -72,6 +76,8 @@ public HeaderFactory getHeaderFactory() {
 	}
 
 	/**
+	 * Sets the factory used to create {@link Header} instances.
+	 *
 	 * @param headerFactory
 	 * 		Factory for creating {@link Header}.
 	 *        {@code null} to use the default factory.
@@ -90,6 +96,8 @@ public ContentWrapperFactory getContentWrapperFactory() {
 	}
 
 	/**
+	 * Sets the factory used to create {@link ContentWrapper} instances.
+	 *
 	 * @param contentWrapperFactory
 	 * 		Factory for creating {@link ContentWrapper}.
 	 *        {@code null} to use the default factory.
@@ -108,6 +116,8 @@ public CanvasFactory getCanvasFactory() {
 	}
 
 	/**
+	 * Sets the factory used to create {@link PixelCanvas} instances.
+	 *
 	 * @param canvasFactory
 	 * 		Factory for creating {@link PixelCanvas}.
 	 *        {@code null} to use the default factory.

core/src/main/java/software/coley/bentofx/building/DockBuilding.java

@@ -19,6 +19,8 @@ public class DockBuilding {
 	private final Bento bento;
 
 	/**
+	 * Creates a builder for the given bento instance.
+	 *
 	 * @param bento
 	 * 		Parent bento instance.
 	 */

core/src/main/java/software/coley/bentofx/building/PlaceholderBuilding.java

@@ -28,6 +28,8 @@ public DockablePlaceholderFactory getDockablePlaceholderFactory() {
 	}
 
 	/**
+	 * Sets the placeholder factory for dockables with no content to show.
+	 *
 	 * @param dockablePlaceholderFactory
 	 * 		Placeholder factory for dockables with no content to show.
 	 */
@@ -43,6 +45,8 @@ public DockContainerLeafPlaceholderFactory getContainerPlaceholderFactory() {
 	}
 
 	/**
+	 * Sets the placeholder factory for containers with no content to show.
+	 *
 	 * @param containerPlaceholderFactory
 	 * 		Placeholder factory for containers with no content to show.
 	 */

core/src/main/java/software/coley/bentofx/building/StageBuilding.java

@@ -236,6 +236,8 @@ protected void initializeFromSource(Scene sourceScene,
 	}
 
 	/**
+	 * Sets the factory used to create new stages.
+	 *
 	 * @param factory
 	 * 		New factory for creating stages.
 	 */
@@ -246,6 +248,8 @@ public void setStageFactory(@Nullable StageFactory factory) {
 	}
 
 	/**
+	 * Sets the factory used to create new scenes.
+	 *
 	 * @param factory
 	 * 		New factory for creating scenes.
 	 */
@@ -256,6 +260,8 @@ public void setSceneFactory(@Nullable SceneFactory factory) {
 	}
 
 	/**
+	 * Sets whether newly created stages have their owner set to the source stage.
+	 *
 	 * @param applySourceAsOwner
 	 *        {@code true} to make newly created stages have their owner set to the source stage the dockable is being dragged out of.
 	 *        {@code false} to not set an owner, allowing the new stage to be handled independently of the source stage.

core/src/main/java/software/coley/bentofx/control/ButtonHBar.java

@@ -15,6 +15,8 @@
  */
 public class ButtonHBar extends HBox {
 	/**
+	 * Creates a horizontal button bar whose children track the given parent's height.
+	 *
 	 * @param parent
 	 * 		Parent region to bind child height to.
 	 * @param children

core/src/main/java/software/coley/bentofx/control/ButtonVBar.java

@@ -15,6 +15,8 @@
  */
 public class ButtonVBar extends VBox {
 	/**
+	 * Creates a vertical button bar whose children track the given parent's width.
+	 *
 	 * @param parent
 	 * 		Parent region to bind child width to.
 	 * @param children

core/src/main/java/software/coley/bentofx/control/ContentWrapper.java

@@ -23,6 +23,8 @@
  */
 public class ContentWrapper extends BorderPane {
 	/**
+	 * Creates a content wrapper with drag-drop handling for the given container.
+	 *
 	 * @param container
 	 * 		Parent container.
 	 */

core/src/main/java/software/coley/bentofx/control/DragDropStage.java

@@ -25,6 +25,8 @@ public class DragDropStage extends Stage {
 	private WeakReference<Parent> content;
 
 	/**
+	 * Creates a drag-drop stage, wiring up close/hide/show handling for its content.
+	 *
 	 * @param autoCloseWhenEmpty
 	 * 		Flag to determine if this stage should auto-close if its sole content is removed.
 	 * 		See	{@link #isAutoCloseWhenEmpty()} for more details.
@@ -71,11 +73,11 @@ public DragDropStage(boolean autoCloseWhenEmpty) {
 
 	/**
 	 * <b>Context:</b>These stages are created when a user drags a {@link Header} into empty space.
-	 * <p/>
+	 * <p>
 	 * Most of the time, if a user drags the {@link Header} from this stage into some other place in another stage,
 	 * leaving this stage with nothing in {@link DockContainer} it would be ideal to automatically
 	 * close this window.
-	 * <p/>
+	 * <p>
 	 * When this is {@code true} we do just that.
 	 *
 	 * @return {@code true} when this stage should auto-close if its {@link DockContainer} is cleared/removed.

core/src/main/java/software/coley/bentofx/control/Header.java

@@ -72,6 +72,8 @@ public class Header extends Region {
 	private double insertionMidpoint = Double.NaN;
 
 	/**
+	 * Creates a header wrapping the given dockable.
+	 *
 	 * @param dockable
 	 * 		Dockable to wrap.
 	 * @param parentPane

core/src/main/java/software/coley/bentofx/control/HeaderPane.java

@@ -40,6 +40,8 @@ public class HeaderPane extends BorderPane {
 	private @Nullable Headers headers;
 
 	/**
+	 * Creates a header pane for the given container.
+	 *
 	 * @param container
 	 * 		Parent container.
 	 */

core/src/main/java/software/coley/bentofx/control/Headers.java

@@ -23,6 +23,8 @@
  */
 public class Headers extends LinearItemPane {
 	/**
+	 * Creates a headers pane laying out the given container's headers.
+	 *
 	 * @param container
 	 * 		Parent container.
 	 * @param orientation

core/src/main/java/software/coley/bentofx/control/LinearItemPane.java

@@ -30,6 +30,8 @@ public class LinearItemPane extends Pane {
 	private final ObjectProperty<Node> keepInView = new SimpleObjectProperty<>();
 
 	/**
+	 * Creates a linear item pane laid out along the given axis.
+	 *
 	 * @param orientation
 	 * 		Which axis to layout children on.
 	 */

core/src/main/java/software/coley/bentofx/control/canvas/ArgbBufferedImageSource.java

@@ -16,6 +16,8 @@ public class ArgbBufferedImageSource implements ArgbSource {
 	private int hash;
 
 	/**
+	 * Wraps the given image as an ARGB source.
+	 *
 	 * @param image
 	 * 		Wrapped image.
 	 */

core/src/main/java/software/coley/bentofx/control/canvas/ArgbImageSource.java

@@ -18,6 +18,8 @@ public class ArgbImageSource implements ArgbSource {
 	private int hash;
 
 	/**
+	 * Wraps the given image as an ARGB source.
+	 *
 	 * @param image
 	 * 		Wrapped image.
 	 */

core/src/main/java/software/coley/bentofx/dockable/Dockable.java

@@ -45,6 +45,8 @@ public class Dockable implements BentoBacked, Identifiable {
 	private @Nullable List<DockableCloseListener> closeListeners;
 
 	/**
+	 * Creates a dockable.
+	 *
 	 * @param bento
 	 * 		Parent bento instance.
 	 * @param identifier
@@ -72,6 +74,8 @@ public void fireCloseListeners() {
 	}
 
 	/**
+	 * Runs the given action with this dockable's parent container, if one exists.
+	 *
 	 * @param consumer
 	 * 		Action to run in the parent container, if one exists.
 	 */
@@ -82,6 +86,8 @@ public void inContainer(Consumer<DockContainerLeaf> consumer) {
 	}
 
 	/**
+	 * Runs the given action with this dockable and its parent container, if one exists.
+	 *
 	 * @param consumer
 	 * 		Action to run in the parent container, if one exists.
 	 */
@@ -137,6 +143,8 @@ public StringProperty titleProperty() {
 	}
 
 	/**
+	 * Sets the title.
+	 *
 	 * @param title
 	 * 		New title.
 	 */
@@ -164,6 +172,8 @@ public ObjectProperty<Tooltip> tooltipProperty() {
 	}
 
 	/**
+	 * Sets the tooltip.
+	 *
 	 * @param tooltip
 	 * 		New tooltip.
 	 */
@@ -190,6 +200,8 @@ public ObjectProperty<DockableIconFactory> iconFactoryProperty() {
 	}
 
 	/**
+	 * Sets the icon factory.
+	 *
 	 * @param iconFactory
 	 * 		New icon factory.
 	 */
@@ -217,6 +229,8 @@ public ObjectProperty<DockableMenuFactory> contextMenuFactoryProperty() {
 	}
 
 	/**
+	 * Sets the context menu factory.
+	 *
 	 * @param contextMenuFactory
 	 * 		New context menu factory.
 	 */
@@ -244,6 +258,8 @@ public ObjectProperty<Node> nodeProperty() {
 	}
 
 	/**
+	 * Sets the node to display when this dockable is selected.
+	 *
 	 * @param node
 	 * 		New node to display when this dockable is selected.
 	 */
@@ -271,6 +287,8 @@ public ObjectProperty<DockContainerLeaf> containerProperty() {
 	}
 
 	/**
+	 * Sets the parent container.
+	 *
 	 * @param container
 	 * 		New parent container.
 	 */
@@ -299,6 +317,8 @@ public IntegerProperty dragGroupMaskProperty() {
 	}
 
 	/**
+	 * Sets the drag group mask.
+	 *
 	 * @param dragGroupMask
 	 * 		New drag group mask.
 	 */
@@ -325,6 +345,8 @@ public BooleanProperty closableProperty() {
 	}
 
 	/**
+	 * Sets whether this dockable is closable.
+	 *
 	 * @param closable
 	 *        {@code true} to make this dockable closable. {@code false} to disable closure.
 	 */
@@ -351,6 +373,8 @@ public BooleanProperty canBeDraggedProperty() {
 	}
 
 	/**
+	 * Sets whether this dockable can be dragged.
+	 *
 	 * @param canBeDragged
 	 *        {@code true} to make this dockable draggable. {@code false} to make it not draggable.
 	 */
@@ -377,6 +401,8 @@ public BooleanProperty canBeDroppedToNewWindowProperty() {
 	}
 
 	/**
+	 * Sets whether this dockable can be drag-dropped to a new window.
+	 *
 	 * @param canBeDroppedToNewWindow
 	 *        {@code true} to allow this dockable to be drag-dropped to a new window. {@code false} to limit to cross-container dragging.
 	 */

core/src/main/java/software/coley/bentofx/dockable/DockableCloseListener.java

@@ -10,6 +10,8 @@
  */
 public interface DockableCloseListener {
 	/**
+	 * Called when the dockable is closed.
+	 *
 	 * @param path
 	 * 		Path to dockable prior to closure.
 	 * @param dockable

core/src/main/java/software/coley/bentofx/dockable/DockableDragDropBehavior.java

@@ -14,14 +14,14 @@ public interface DockableDragDropBehavior {
 	 * Determines if a given dockable can be placed into a container.
 	 * Generally this is used to control how the {@link Dockable#getDragGroupMask()} behaves.
 	 * You can override this method to support alternative grouping models.
-	 * <p/>
+	 * <p>
 	 * For example, the default implementation is a simple equality check.
 	 * Any dockable can be put into a container that has other dockables of the same mask.
 	 * <pre>{@code
 	 * return targetContainer.getDockables().stream()
 	 * 		.anyMatch(d -> d.getDragMask() == dockable.getDragMask());
 	 * }</pre>
-	 * <p/>
+	 * <p>
 	 * As an alternative, you can make the mask... more like a mask!
 	 * In this example, drag groups are specified as bit-masks, allowing more fine-control over
 	 * what can go where.

core/src/main/java/software/coley/bentofx/dockable/DockableMoveListener.java

@@ -10,6 +10,8 @@
  */
 public interface DockableMoveListener {
 	/**
+	 * Called when the dockable is moved to a new location.
+	 *
 	 * @param oldPath
 	 * 		Path to old dockable location.
 	 * @param newPath

core/src/main/java/software/coley/bentofx/dockable/DockableOpenListener.java

@@ -10,6 +10,8 @@
  */
 public interface DockableOpenListener {
 	/**
+	 * Called when the dockable is opened.
+	 *
 	 * @param path
 	 * 		Path to opened dockable.
 	 * @param dockable