Add reference to HardwareKeyboard in RawKeyboard documentation (#118607)

Author: bleroux

packages/flutter/lib/src/services/raw_keyboard.dart

@@ -585,13 +585,32 @@ typedef RawKeyEventHandler = bool Function(RawKeyEvent event);
 /// These key events are typically only key events generated by a hardware
 /// keyboard, and not those from software keyboards or input method editors.
 ///
+/// ## Compared to [HardwareKeyboard]
+///
+/// [RawKeyboard] is the legacy API, and will be deprecated and removed in the
+/// future. It is recommended to always use [HardwareKeyboard] and [KeyEvent]
+/// APIs (such as [FocusNode.onKeyEvent]) to handle key events.
+///
+/// Behavior-wise, [RawKeyboard] provides a less unified, less regular
+/// event model than [HardwareKeyboard]. For example:
+///
+///  * Down events might not be matched with an up event, and vice versa (the
+///    set of pressed keys is silently updated).
+///  * The logical key of the down event might not be the same as that of the up
+///    event.
+///  * Down events and repeat events are not easily distinguishable (must be
+///    tracked manually).
+///  * Lock modes (such as CapsLock) only have their "enabled" state recorded.
+///    There's no way to acquire their pressing state.
+///
 /// See also:
 ///
 ///  * [RawKeyDownEvent] and [RawKeyUpEvent], the classes used to describe
 ///    specific raw key events.
 ///  * [RawKeyboardListener], a widget that listens for raw key events.
 ///  * [SystemChannels.keyEvent], the low-level channel used for receiving
 ///    events from the system.
+///  * [HardwareKeyboard], the recommended replacement.
 class RawKeyboard {
   RawKeyboard._();