align JavaDoc with web component

vaadin · Jan 22, 2025 · e359ef8 · e359ef8
1 parent f7c2d9f
commit e359ef8
Show file tree

Hide file tree

Showing 2 changed files with 28 additions and 29 deletions.
diff --git a/...flow-parent/vaadin-button-flow/src/main/java/com/vaadin/flow/component/button/Button.java b/...flow-parent/vaadin-button-flow/src/main/java/com/vaadin/flow/component/button/Button.java
@@ -350,18 +350,18 @@ public boolean isDisableOnClick() {
     }
 
     /**
-     * Sets the button explicitly disabled or enabled. When disabled, prevents
-     * all user interactions with the button such as clicking or hovering, and
-     * removes the button from the tab order, which makes it unreachable via the
-     * keyboard navigation.
+     * Sets the button explicitly disabled or enabled. When disabled, the button
+     * is rendered as "dimmed" and prevents all user interactions (mouse and
+     * keyboard).
      * <p>
-     * While the default behavior effectively prevents accidental interactions,
-     * it has an accessibility drawback: screen readers skip disabled buttons
-     * entirely, and users can't see tooltips that might explain why the button
-     * is disabled. To address this, an experimental enhancement allows disabled
-     * buttons to receive focus and show tooltips, while still preventing other
-     * interactions. This feature can be enabled by setting the following
-     * feature flag in {@code vaadin-featureflags.properties}:
+     * Since disabled buttons are not focusable and cannot react to hover events
+     * by default, it can cause accessibility issues by making them entirely
+     * invisible to assistive technologies, and prevents the use of Tooltips to
+     * explain why the action is not available. This can be addressed with the
+     * feature flag {@code accessibleDisabledButtons}, which makes disabled
+     * buttons focusable and hoverable, while preventing them from being
+     * triggered. To enable this feature flag, add the following line to
+     * {@code src/main/resources/vaadin-featureflags.properties}:
      *
      * <pre>
      * com.vaadin.experimental.accessibleDisabledButtons = true
@@ -380,8 +380,8 @@ public void setEnabled(boolean enabled) {
      * {@inheritDoc}
      * <p>
      * By default, focus shortcuts are only active when the button is enabled.
-     * To make disabled buttons also focusable, set the following feature flag
-     * in {@code vaadin-featureflags.properties}:
+     * To make disabled buttons also focusable, enable the following feature
+     * flag in {@code src/main/resources/vaadin-featureflags.properties}:
      *
      * <pre>
      * com.vaadin.experimental.accessibleDisabledButtons = true
@@ -405,8 +405,8 @@ public ShortcutRegistration addFocusShortcut(Key key,
      * {@inheritDoc}
      * <p>
      * By default, buttons are only focusable in the enabled state. To make
-     * disabled buttons also focusable, set the following feature flag in
-     * {@code vaadin-featureflags.properties}:
+     * disabled buttons also focusable, enable the following feature flag in
+     * {@code src/main/resources/vaadin-featureflags.properties}:
      *
      * <pre>
      * com.vaadin.experimental.accessibleDisabledButtons = true
@@ -433,8 +433,8 @@ public Registration addFocusListener(
      * {@inheritDoc}
      * <p>
      * By default, buttons are only focusable in the enabled state. To make
-     * disabled buttons also focusable, set the following feature flag in
-     * {@code vaadin-featureflags.properties}:
+     * disabled buttons also focusable, enable the following feature flag in
+     * {@code src/main/resources/vaadin-featureflags.properties}:
      *
      * <pre>
      * com.vaadin.experimental.accessibleDisabledButtons = true

diff --git a/...ent/vaadin-menu-bar-flow/src/main/java/com/vaadin/flow/component/menubar/MenuBarItem.java b/...ent/vaadin-menu-bar-flow/src/main/java/com/vaadin/flow/component/menubar/MenuBarItem.java
@@ -37,19 +37,18 @@ protected MenuBarSubMenu createSubMenu() {
     }
 
     /**
-     * Sets the menu item explicitly disabled or enabled. When disabled,
-     * prevents all user interactions with it, such as focusing, clicking,
-     * opening a sub-menu, etc. The item is also removed from the tab order,
-     * which makes it unreachable via the keyboard navigation.
+     * Sets the menu item explicitly disabled or enabled. When disabled, the
+     * menu item is rendered as "dimmed" and prevents all user interactions
+     * (mouse and keyboard).
      * <p>
-     * While the default behavior effectively prevents accidental interactions,
-     * it has an accessibility drawback: screen readers skip disabled root-level
-     * items (menu bar buttons) entirely, and users can't see tooltips that
-     * might explain why the button is disabled. To improve this, an
-     * experimental enhancement allows disabled menu bar buttons to receive
-     * focus and show tooltips, while still preventing other interactions. This
-     * feature can be enabled by setting the following feature flag in
-     * {@code vaadin-featureflags.properties}:
+     * Since disabled buttons (root-level items) are not focusable and cannot
+     * react to hover events by default, it can cause accessibility issues by
+     * making them entirely invisible to assistive technologies, and prevents
+     * the use of Tooltips to explain why the action is not available. This can
+     * be addressed with the feature flag {@code accessibleDisabledButtons},
+     * which makes disabled buttons focusable and hoverable, while preventing
+     * them from being triggered. To enable this feature flag, add the following
+     * line to {@code src/main/resources/vaadin-featureflags.properties}:
      *
      * <pre>
      * com.vaadin.experimental.accessibleDisabledButtons = true