From e359ef85fc4e8bca9406c521fdafc6354933048c Mon Sep 17 00:00:00 2001
From: Sergey Vinogradov <mr.vursen@gmail.com>
Date: Wed, 22 Jan 2025 10:17:29 +0400
Subject: [PATCH] align JavaDoc with web component

---
 .../vaadin/flow/component/button/Button.java  | 34 +++++++++----------
 .../flow/component/menubar/MenuBarItem.java   | 23 ++++++-------
 2 files changed, 28 insertions(+), 29 deletions(-)

diff --git a/vaadin-button-flow-parent/vaadin-button-flow/src/main/java/com/vaadin/flow/component/button/Button.java b/vaadin-button-flow-parent/vaadin-button-flow/src/main/java/com/vaadin/flow/component/button/Button.java
index e532e7a110e..539e457d14f 100644
--- a/vaadin-button-flow-parent/vaadin-button-flow/src/main/java/com/vaadin/flow/component/button/Button.java
+++ b/vaadin-button-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/vaadin-menu-bar-flow-parent/vaadin-menu-bar-flow/src/main/java/com/vaadin/flow/component/menubar/MenuBarItem.java b/vaadin-menu-bar-flow-parent/vaadin-menu-bar-flow/src/main/java/com/vaadin/flow/component/menubar/MenuBarItem.java
index dc0337b0ade..1d115622139 100644
--- a/vaadin-menu-bar-flow-parent/vaadin-menu-bar-flow/src/main/java/com/vaadin/flow/component/menubar/MenuBarItem.java
+++ b/vaadin-menu-bar-flow-parent/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