Fix some javadoc issues in order to make deployment work (#13)

flexdock-core/src/main/java/org/flexdock/docking/DockingConstants.java

@@ -69,15 +69,12 @@ public interface DockingConstants {
      *
      * @see java.beans.PropertyChangeListener
      * @see Dockable#addPropertyChangeListener(java.beans.PropertyChangeListener)
-     * @see org.flexdock.view.Titlebar
      */
     String PIN_ACTION = "pin";
 
     /**
      * A constant representing a "close" action. Such actions are added to title
      * bars to enable the close effect.
-     *
-     * @see org.flexdock.view.Titlebar
      */
     String CLOSE_ACTION = "close";
 

flexdock-core/src/main/java/org/flexdock/docking/DockingManager.java

@@ -652,12 +652,12 @@ public static boolean isFloatingEnabled() {
 
     /**
      * Indicates whether tabbed layouts are supported by default for
-     * {@code DockingPorts} with a single {@code Dockable} in the CENTER region.
-     * This is a global default setting and applies to any <cod>DockingPort}
+     * {@code DockingPorts} with a single {@code Dockable} in the {@link DockingConstants#CENTER} region.
+     * This is a global default setting and applies to any {@code DockingPort}
      * that does not have a specific contradictory local setting.
      * <p>
      * This method defers processing to
-     * {@code org.flexdock.docking.props.PropertyManager.getDockingPortRoot()}.
+     * {@link org.flexdock.docking.props.PropertyManager#getDockingPortRoot()}.
      * As such, there are multiple "scopes" at which this property may be
      * overridden.
      *
@@ -1293,8 +1293,8 @@ public static RootDockingPortInfo getRootDockingPortInfo(Component comp) {
      *
      * @return {@code true} if the current layout model was succesfully stored,
      *         {@code false} otherwise.
-     * @throws IOException
-     * @throws PersisterException
+     * @throws IOException if an I/O exception occurs during storage
+     * @throws PersistenceException wraps all specific exceptions which can occur during storage
      * @see #getLayoutManager()
      * @see #setLayoutManager(LayoutManager)
      * @see LayoutManager#store()
@@ -1326,8 +1326,8 @@ public static boolean storeLayoutModel() throws IOException,
      *
      * @return {@code true} if the current layout model was succesfully loaded,
      *         {@code false} otherwise.
-     * @throws IOException
-     * @throws PersisterException
+     * @throws IOException if an I/O exception occurs during loading
+     * @throws PersistenceException wraps all specific exceptions which can occur during loading
      * @see #loadLayoutModel(boolean)
      * @see LayoutManager#load()
      */
@@ -1358,10 +1358,11 @@ public static boolean loadLayoutModel() throws IOException,
      * previous layout model found in storage). If a problem occurs during the
      * loading process, an {@code IOException} is thrown.
      *
+     * @param restore whether or not to restore the loaded layout
      * @return {@code true} if the current layout model was succesfully loaded,
      *         {@code false} otherwise.
-     * @throws IOException
-     * @throws PersisterException
+     * @throws IOException if an I/O exception occurs during loading
+     * @throws PersistenceException wraps all specific exceptions which can occur during loading
      * @see #getLayoutManager()
      * @see #setLayoutManager(LayoutManager)
      * @see #restoreLayout(boolean)
@@ -1394,7 +1395,6 @@ public static boolean loadLayoutModel(boolean restore) throws IOException,
      *
      * @return {@code true} if the in-memory layout model was properly restored
      *         to the application view, {@code false} otherwise.
-     * @throws PersisterException
      * @see #restoreLayout(boolean)
      * @see #getLayoutManager()
      * @see #setLayoutManager(LayoutManager)
@@ -1435,7 +1435,8 @@ public static boolean restoreLayout() {
      *            storage into memory before synchronizing the application view.
      * @return {@code true} if the in-memory layout model was properly restored
      *         to the application view, {@code false} otherwise.
-     * @throws PersisterException
+     * @throws IOException if an I/O exception occurs during restoring
+     * @throws PersistenceException wraps all specific exceptions which can occur during restoring
      * @see #getLayoutManager()
      * @see #setLayoutManager(LayoutManager)
      * @see LayoutManager#restore(boolean)
@@ -2742,7 +2743,7 @@ public static void setDragPreview(DragPreview dragPreview) {
      * obtaining the {@code Dockable} associated to the component via
      * {@link #getDockable(Component)}.
      *
-     * @param comp
+     * @param comp the component to toggle maximization for
      * @see #toggleMaximized(Dockable)
      */
     public static void toggleMaximized(Component comp) {
@@ -2766,7 +2767,7 @@ public static void toggleMaximized(Component comp) {
      * {@code DockingPort} is asked to return to its original state and the
      * {@code Dockable} is returned to its original {@code DockingPort}.
      *
-     * @param dockable
+     * @param dockable the dockable to toggle maximization for
      */
     public static void toggleMaximized(Dockable dockable) {
         DockingPort rootPort = getRootDockingPort(dockable.getComponent());

flexdock-core/src/main/java/org/flexdock/docking/DockingPort.java

@@ -44,6 +44,10 @@ public interface DockingPort extends DockingListener, DockingMonitor {
     /**
      * Returns a boolean indicating whether or not docking is allowed within the
      * specified region. Used by {@code DockingManager} during drag operations.
+     *
+     * @param comp the component to check
+     * @param region the region to check
+     * @return {@code true} if docking is allowed for {@code comp} in {@code region}, {@code false} otherwise
      */
     boolean isDockingAllowed(Component comp, String region);
 
@@ -53,20 +57,27 @@ public interface DockingPort extends DockingListener, DockingMonitor {
     void clear();
 
     /**
-     * Docks the specified Dockable in the specified region. The
-     * {@code Dockable's} {@code getDockable()} component is used as the docking
-     * component.
+     * Docks the specified Dockable in the specified region.
+     *
+     * @param dockable the dockable to dock
+     * @param region the region where to dock
+     * @return {@code true} if the docking was successful, {@code false} otherwise
      */
     boolean dock(Dockable dockable, String region);
 
     /**
-     * Docks the specified Component in the specified region. Returns
-     * {@code true} for success and {@code false} for failure.
+     * Docks the specified component in the specified region.
+     *
+     * @param comp the component to dock
+     * @param region the region where to dock
+     * @return {@code true} for success and {@code false} for failure
      */
     boolean dock(Component comp, String region);
 
     /**
      * Returns a reference to the currently docked component.
+     *
+     * @return as described
      */
     Component getDockedComponent();
 
@@ -75,6 +86,9 @@ public interface DockingPort extends DockingListener, DockingMonitor {
      * Returns null if there is no Dockable there. If a tabbed layout is
      * present, this method will return the Dockable in the currently selected
      * tab.
+     *
+     * @param region the region to retrieve for
+     * @return as described
      */
     Dockable getDockable(String region);
 
@@ -83,6 +97,9 @@ public interface DockingPort extends DockingListener, DockingMonitor {
      * Returns null if there is no Component there. If a tabbed layout is
      * present, this method will return the Component in the currently selected
      * tab.
+     *
+     * @param region the region to retrieve for
+     * @return as described
      */
     Component getComponent(String region);
 
@@ -96,6 +113,8 @@ public interface DockingPort extends DockingListener, DockingMonitor {
      * instances, but it should also be consistent from JVM to JVM so that the
      * association between a {@code DockingPort} instance and its ID can be
      * remembered from session to session.
+     *
+     * @return as described
      */
     String getPersistentId();
 
@@ -109,14 +128,19 @@ public interface DockingPort extends DockingListener, DockingMonitor {
     void setPersistentId(String id);
 
     /**
-     * Indicates whether or not the specified component is a child component
+     * Checks whether or not the specified component is a child component
      * docked within the {@code DockingPort}.
+     *
+     * @param comp the component to check
+     * @return {@code true} if {@code comp} is a parent docking port, {@code false} otherwise
      */
     boolean isParentDockingPort(Component comp);
 
     /**
-     * Removes the specified Component in from the {@code DockingPort}. Returns
-     * {@code true} for success and {@code false} for failure.
+     * Removes the specified Component in from the {@code DockingPort}.
+     *
+     * @param comp the component to undock
+     * @return {@code true} for success and {@code false} for failure
      */
     boolean undock(Component comp);
 
@@ -128,17 +152,17 @@ public interface DockingPort extends DockingListener, DockingMonitor {
      * {@code SOUTH_REGION}, {@code EAST_REGION}, {@code WEST_REGION}, or
      * {@code UNKNOWN_REGION}.
      *
+     * @param point the point to retrieve the region for
      * @return the region containing the specified {@code Point}.
      */
-    String getRegion(Point p);
+    String getRegion(Point point);
 
     /**
      * Returns the value of the property with the specified key. Only properties
      * added with {@code putClientProperty} will return a non-{@code null}
      * value.
      *
-     * @param key
-     *            the being queried
+     * @param key the key being queried
      * @return the value of this property or {@code null}
      * @see javax.swing.JComponent#getClientProperty(java.lang.Object)
      */
@@ -148,6 +172,8 @@ public interface DockingPort extends DockingListener, DockingMonitor {
      * Adds an arbitrary key/value "client property" to this {@code DockingPort}.
      * {@code null} values are allowed.
      *
+     * @param key the key being set
+     * @param value the value to set for {@code key}
      * @see javax.swing.JComponent#putClientProperty(java.lang.Object,
      *      java.lang.Object)
      */
@@ -178,6 +204,7 @@ public interface DockingPort extends DockingListener, DockingMonitor {
      * Returns the {@code DockingStrategy} instance used by this
      * {@code DockingPort} for docking operations.
      *
+     * @return as described
      * @see DockingStrategy
      */
     DockingStrategy getDockingStrategy();
@@ -201,6 +228,8 @@ public interface DockingPort extends DockingListener, DockingMonitor {
      * method will return {@code false}. If the this {@code DockingPort} is not
      * validated and/or is not part of a container hierarchy, this method should
      * return {@code true}.
+     *
+     * @return as described
      */
     boolean isRoot();
 

flexdock-core/src/main/java/org/flexdock/docking/DockingStub.java

@@ -31,6 +31,7 @@ public interface DockingStub {
      * operations. The component may or may not be the same as the Component
      * returned by {@code getFrameDragSource()}.
      *
+     * @return as described
      * @see #getFrameDragSource()
      */
     Component getDragSource();
@@ -46,6 +47,7 @@ public interface DockingStub {
      * reposition" behavior will supercede any "drag-to-dock" behavior while
      * this stub is in a floating state.
      *
+     * @return as described
      * @see #getDragSource()
      */
     Component getFrameDragSource();
@@ -63,6 +65,8 @@ public interface DockingStub {
      * <p>
      * The framework performs indexing on the persistent ID. Consequently, this
      * method may <b>not</b> return a {@code null} reference.
+     *
+     * @return as described
      */
     String getPersistentId();
 

flexdock-core/src/main/java/org/flexdock/docking/defaults/DefaultDockingPort.java

@@ -295,8 +295,6 @@ public void invalidateLayout(Container target) {
     /**
      * Creates a new {@code DefaultDockingPort} with a persistent ID equal to
      * the {@code String} value of this a random UUID.
-     *
-     * @see org.flexdock.util.UUID
      */
     public DefaultDockingPort() {
         this(UUID.randomUUID().toString());
@@ -1686,7 +1684,7 @@ private Component setComponent(Component c) {
      * there i s a container hierarchy to manage tabbed interfaces, split
      * layouts, and sub-docking. As components are removed from this hierarchy,
      * the hierarchy itself must be reevaluated. Removing a component from a
-     * child code>DefaultDockingPort} within a {@code JSplitPane} renders the
+     * child {@code DefaultDockingPort} within a {@code JSplitPane} renders the
      * child {@code DefaultDockingPort} unnecessary, which, in turn, renders the
      * notion of splitting the layout with a {@code JSplitPane} unnecessary
      * (since there are no longer two components to split the layout between).
@@ -1805,7 +1803,7 @@ protected boolean isValidDockableChild(Component c, Class desiredClass) {
      *
      * @param listener
      *            the {@code DockingListener} to add to this {@code DockingPort}.
-     * @see DockingMonitor#addDockingListener(DockingListener)
+     * @see org.flexdock.docking.event.DockingMonitor#addDockingListener(DockingListener)
      * @see #getDockingListeners()
      * @see #removeDockingListener(DockingListener)
      */
@@ -1823,7 +1821,7 @@ public void addDockingListener(DockingListener listener) {
      *
      * @return an array of all {@code DockingListeners} added to this
      *         {@code DockingPort}.
-     * @see DockingMonitor#getDockingListeners()
+     * @see org.flexdock.docking.event.DockingMonitor#getDockingListeners()
      * @see #addDockingListener(DockingListener)
      * @see #removeDockingListener(DockingListener)
      */
@@ -1843,7 +1841,7 @@ public DockingListener[] getDockingListeners() {
      * @param listener
      *            the {@code DockingListener} to remove from this
      *            {@code DockingPort}
-     * @see DockingMonitor#removeDockingListener(DockingListener)
+     * @see org.flexdock.docking.event.DockingMonitor#removeDockingListener(DockingListener)
      * @see #addDockingListener(DockingListener)
      * @see #getDockingListeners()
      */