[Shortcuts] Improve documentation (#123499)

[Shortcuts] Improve documentation

packages/flutter/lib/src/widgets/actions.dart

@@ -43,6 +43,8 @@ BuildContext _getParent(BuildContext context) {
 ///
 /// See also:
 ///
+///  * [Shortcuts], a widget used to bind key combinations to [Intent]s.
+///  * [Actions], a widget used to map [Intent]s to [Action]s.
 ///  * [Actions.invoke], which invokes the action associated with a specified
 ///    [Intent] using the [Actions] widget that most tightly encloses the given
 ///    [BuildContext].
@@ -67,13 +69,14 @@ abstract class Intent with Diagnosticable {
 /// To register an action listener, call [Action.addActionListener].
 typedef ActionListenerCallback = void Function(Action<Intent> action);
 
-/// Base class for actions.
+/// Base class for an action or command to be performed.
+///
+/// {@youtube 560 315 https://www.youtube.com/watch?v=XawP1i314WM}
 ///
-/// As the name implies, an [Action] is an action or command to be performed.
-/// They are typically invoked as a result of a user action, such as a keyboard
-/// shortcut in a [Shortcuts] widget, which is used to look up an [Intent],
-/// which is given to an [ActionDispatcher] to map the [Intent] to an [Action]
-/// and invoke it.
+/// [Action]s are typically invoked as a result of a user action. For example,
+/// the [Shortcuts] widget will map a keyboard shortcut into an [Intent], which
+/// is given to an [ActionDispatcher] to map the [Intent] to an [Action] and
+/// invoke it.
 ///
 /// The [ActionDispatcher] can invoke an [Action] on the primary focus, or
 /// without regard for focus.
@@ -612,13 +615,13 @@ class ActionDispatcher with Diagnosticable {
   }
 }
 
-/// A widget that establishes an [ActionDispatcher] and a map of [Intent] to
-/// [Action] to be used by its descendants when invoking an [Action].
+/// A widget that maps [Intent]s to [Action]s to be used by its descendants
+/// when invoking an [Action].
 ///
 /// {@youtube 560 315 https://www.youtube.com/watch?v=XawP1i314WM}
 ///
-/// Actions are typically invoked using [Actions.invoke] with the context
-/// containing the ambient [Actions] widget.
+/// Actions are typically invoked using [Shortcuts]. They can also be invoked
+/// using [Actions.invoke] on a context containing an ambient [Actions] widget.
 ///
 /// {@tool dartpad}
 /// This example creates a custom [Action] subclass `ModifyAction` for modifying
@@ -641,12 +644,12 @@ class ActionDispatcher with Diagnosticable {
 ///
 /// See also:
 ///
-///  * [ActionDispatcher], the object that this widget uses to manage actions.
+///  * [Shortcuts], a widget used to bind key combinations to [Intent]s.
+///  * [Intent], a class that contains configuration information for running an
+///    [Action].
 ///  * [Action], a class for containing and defining an invocation of a user
 ///    action.
-///  * [Intent], a class that holds a unique [LocalKey] identifying an action,
-///    as well as configuration information for running the [Action].
-///  * [Shortcuts], a widget used to bind key combinations to [Intent]s.
+///  * [ActionDispatcher], the object that this widget uses to manage actions.
 class Actions extends StatefulWidget {
   /// Creates an [Actions] widget.
   ///
@@ -664,7 +667,7 @@ class Actions extends StatefulWidget {
   ///
   /// If this [dispatcher] is null, then [Actions.of] and [Actions.invoke] will
   /// look up the tree until they find an Actions widget that has a dispatcher
-  /// set. If not such widget is found, then they will return/use a
+  /// set. If no such widget is found, then they will return/use a
   /// default-constructed [ActionDispatcher].
   final ActionDispatcher? dispatcher;
 

packages/flutter/lib/src/widgets/shortcuts.dart

@@ -869,6 +869,13 @@ class ShortcutManager with Diagnosticable, ChangeNotifier {
 /// when invoking an [Action] via a keyboard key combination that maps to an
 /// [Intent].
 ///
+/// This is similar to but more powerful than the [CallbackShortcuts] widget.
+/// Unlike [CallbackShortcuts], this widget separates key bindings and their
+/// implementations. This separation allows [Shortcuts] to have key bindings
+/// that adapt to the focused context. For example, the desired action for a
+/// deletion intent may be to delete a character in a text input, or to delete
+/// a file in a file menu.
+///
 /// See the article on [Using Actions and
 /// Shortcuts](https://docs.flutter.dev/development/ui/advanced/actions_and_shortcuts)
 /// for a detailed explanation.
@@ -903,8 +910,8 @@ class ShortcutManager with Diagnosticable, ChangeNotifier {
 ///
 /// See also:
 ///
-///  * [CallbackShortcuts], a less complicated (but less flexible) way of
-///    defining key bindings that just invoke callbacks.
+///  * [CallbackShortcuts], a simpler but less flexible widget that defines key
+///    bindings that invoke callbacks.
 ///  * [Intent], a class for containing a description of a user action to be
 ///    invoked.
 ///  * [Action], a class for defining an invocation of a user action.
@@ -1038,32 +1045,32 @@ class _ShortcutsState extends State<Shortcuts> {
   }
 }
 
-/// A widget that provides an uncomplicated mechanism for binding a key
-/// combination to a specific callback.
-///
-/// This is similar to the functionality provided by the [Shortcuts] widget, but
-/// instead of requiring a mapping to an [Intent], and an [Actions] widget
-/// somewhere in the widget tree to bind the [Intent] to, it just takes a set of
-/// bindings that bind the key combination directly to a [VoidCallback].
+/// A widget that binds key combinations to specific callbacks.
 ///
-/// Because it is a simpler mechanism, it doesn't provide the ability to disable
-/// the callbacks, or to separate the definition of the shortcuts from the
-/// definition of the code that is triggered by them (the role that actions play
-/// in the [Shortcuts]/[Actions] system).
+/// This is similar to but simpler than the [Shortcuts] widget as it doesn't
+/// require [Intent]s and [Actions] widgets. Instead, it accepts a map
+/// of [ShortcutActivator]s to [VoidCallback]s.
 ///
-/// However, for some applications the complexity and flexibility of the
-/// [Shortcuts] and [Actions] mechanism is overkill, and this widget is here for
-/// those apps.
+/// Unlike [Shortcuts], this widget does not separate key bindings and their
+/// implementations. This separation allows [Shortcuts] to have key bindings
+/// that adapt to the focused context. For example, the desired action for a
+/// deletion intent may be to delete a character in a text input, or to delete
+/// a file in a file menu.
 ///
 /// [Shortcuts] and [CallbackShortcuts] can both be used in the same app. As
 /// with any key handling widget, if this widget handles a key event then
 /// widgets above it in the focus chain will not receive the event. This means
 /// that if this widget handles a key, then an ancestor [Shortcuts] widget (or
-/// any other key handling widget) will not receive that key, and similarly, if
+/// any other key handling widget) will not receive that key. Similarly, if
 /// a descendant of this widget handles the key, then the key event will not
 /// reach this widget for handling.
 ///
+/// See the article on [Using Actions and
+/// Shortcuts](https://docs.flutter.dev/development/ui/advanced/actions_and_shortcuts)
+/// for a detailed explanation.
+///
 /// See also:
+///  * [Shortcuts], a more powerful widget for defining key bindings.
 ///  * [Focus], a widget that defines which widgets can receive keyboard focus.
 class CallbackShortcuts extends StatelessWidget {
   /// Creates a const [CallbackShortcuts] widget.