docs: improve Popover JavaDoc, add default values (#6557)

* docs: improve Popover JavaDoc, add default values * docs: mention setBackdropVisible in setModal and vice versa --------- Co-authored-by: Sascha Ißbrücker <[email protected]>
vaadin · Aug 21, 2024 · d8a9405 · d8a9405
1 parent 414a33c
commit d8a9405
Showing 1 changed file with 40 additions and 22 deletions.
diff --git a/...w-parent/vaadin-popover-flow/src/main/java/com/vaadin/flow/component/popover/Popover.java b/...w-parent/vaadin-popover-flow/src/main/java/com/vaadin/flow/component/popover/Popover.java
@@ -227,6 +227,7 @@ public boolean isModal() {
      *
      * @param backdropVisible
      *            {@code true} to show the backdrop, {@code false} otherwise.
+     * @see #setModal(boolean)
      */
     public void setBackdropVisible(boolean backdropVisible) {
         getElement().setProperty("withBackdrop", backdropVisible);
@@ -357,17 +358,25 @@ public void setCloseOnOutsideClick(boolean closeOnOutsideClick) {
     }
 
     /**
-     * Sets position of the popover with respect to its target.
+     * Sets position of the popover with respect to its {@code target}.
+     * <p>
+     * NOTE: when the target component is not set, the position does not take
+     * any effect and the popover is rendered in the middle of the screen.
      *
      * @param position
      *            the position to set
+     * @see #setFor(String)
+     * @see #setTarget(Component)
      */
     public void setPosition(PopoverPosition position) {
         getElement().setProperty("position", position.getPosition());
     }
 
     /**
-     * Gets position of the popover with respect to its target.
+     * Gets position of the popover with respect to its {@code target}.
+     * <p>
+     * NOTE: when the target component is not set, the position does not take
+     * any effect and the popover is rendered in the middle of the screen.
      *
      * @return the position
      */
@@ -386,27 +395,27 @@ public PopoverPosition getPosition() {
      * otherwise a warning in the Javascript console is shown.
      *
      * @param id
-     *            the id of component for this popup, can be {@code null} to
-     *            remove the target
+     *            the id of target component for this popover, can be
+     *            {@code null} to remove the target
      */
     public void setFor(String id) {
         getElement().setProperty("for", id);
     }
 
     /**
-     * Gets the {@code id} of target component of this popup, or {@code null} if
-     * the {@code id} was not set.
+     * Gets the {@code id} of target component of the popover, or {@code null}
+     * if the {@code id} was not set.
      *
-     * @return the id of target component of this popup
+     * @return the id of target component for this popover
      * @see #setFor(String)
      */
     public String getFor() {
         return getElement().getProperty("for");
     }
 
     /**
-     * The delay in milliseconds before the popover is opened on target keyboard
-     * focus.
+     * The delay in milliseconds before the popover is opened on target focus.
+     * Defaults to {@code 0}.
      *
      * @param focusDelay
      *            the delay in milliseconds
@@ -416,8 +425,8 @@ public void setFocusDelay(int focusDelay) {
     }
 
     /**
-     * The delay in milliseconds before the popover is opened on target keyboard
-     * focus.
+     * The delay in milliseconds before the popover is opened on target focus.
+     * Defaults to {@code 0}.
      *
      * @return the delay in milliseconds
      */
@@ -427,6 +436,7 @@ public int getFocusDelay() {
 
     /**
      * The delay in milliseconds before the popover is opened on target hover.
+     * Defaults to {@code 0}.
      *
      * @param hoverDelay
      *            the delay in milliseconds
@@ -437,6 +447,7 @@ public void setHoverDelay(int hoverDelay) {
 
     /**
      * The delay in milliseconds before the popover is opened on target hover.
+     * Defaults to {@code 0}.
      *
      * @return the delay in milliseconds
      */
@@ -446,7 +457,9 @@ public int getHoverDelay() {
 
     /**
      * The delay in milliseconds before the popover is closed on losing hover.
-     * On target blur, the popover is closed immediately.
+     * Defaults to {@code 0}.
+     * <p>
+     * NOTE: on target blur, the popover is closed immediately.
      *
      * @param hideDelay
      *            the delay in milliseconds
@@ -457,7 +470,9 @@ public void setHideDelay(int hideDelay) {
 
     /**
      * The delay in milliseconds before the popover is closed on losing hover.
-     * On target blur, the popover is closed immediately.
+     * Defaults to {@code 0}.
+     * <p>
+     * NOTE: on target blur, the popover is closed immediately.
      *
      * @return the delay in milliseconds
      */
@@ -466,7 +481,8 @@ public int getHideDelay() {
     }
 
     /**
-     * Sets whether the popover can be opened via target click.
+     * Sets whether the popover can be opened via target click. Defaults to
+     * {@code true}.
      *
      * @param openOnClick
      *            {@code true} to allow opening the popover via target click,
@@ -478,8 +494,8 @@ public void setOpenOnClick(boolean openOnClick) {
     }
 
     /**
-     * Gets whether the popover can be opened via target click, which is
-     * {@code true} by default.
+     * Gets whether the popover can be opened via target click. Defaults to
+     * {@code true}.
      *
      * @return {@code true} if the popover can be opened with target click,
      *         {@code false} otherwise.
@@ -489,7 +505,8 @@ public boolean isOpenOnClick() {
     }
 
     /**
-     * Sets whether the popover can be opened via target focus.
+     * Sets whether the popover can be opened via target focus. Defaults to
+     * {@code false}.
      *
      * @param openOnFocus
      *            {@code true} to allow opening the popover via target focus,
@@ -501,8 +518,8 @@ public void setOpenOnFocus(boolean openOnFocus) {
     }
 
     /**
-     * Gets whether the popover can be opened via target focus, which is
-     * {@code false} by default.
+     * Gets whether the popover can be opened via target focus. Defaults to
+     * {@code false}.
      *
      * @return {@code true} if the popover can be opened with target focus,
      *         {@code false} otherwise.
@@ -512,7 +529,8 @@ public boolean isOpenOnFocus() {
     }
 
     /**
-     * Sets whether the popover can be opened via target hover.
+     * Sets whether the popover can be opened via target hover. Defaults to
+     * {@code false}.
      *
      * @param openOnHover
      *            {@code true} to allow opening the popover via target hover,
@@ -524,8 +542,8 @@ public void setOpenOnHover(boolean openOnHover) {
     }
 
     /**
-     * Gets whether the popover can be opened via target hover, which is
-     * {@code false} by default.
+     * Gets whether the popover can be opened via target hover. Defaults to
+     * {@code false}.
      *
      * @return {@code true} if the popover can be opened with target hover,
      *         {@code false} otherwise.