update codes per MdePkg doxgen review comments.

[mirror_edk2.git] / MdePkg / Include / Protocol / SimpleTextInEx.h

diff --git a/MdePkg/Include/Protocol/SimpleTextInEx.h b/MdePkg/Include/Protocol/SimpleTextInEx.h
index 3092fcbdd0952e476a4c81c66cb09ef6d13554a5..5baede162ffb6d9810f337ba459a36e18c24e546 100644 (file)
--- a/MdePkg/Include/Protocol/SimpleTextInEx.h
+++ b/MdePkg/Include/Protocol/SimpleTextInEx.h
@@ -1,10 +1,11 @@
 /** @file\r
-  The file defines the protocol to obtain input from the\r
-  ConsoleIn device. The EFI specification requires that the\r
-  EFI_SIMPLE_TEXT_INPUT_PROTOCOL supports the same languages as\r
-  the corresponding\r
+  Simple Text Input Ex protocol from the UEFI 2.0 specification.\r
+  \r
+  This protocol defines an extension to the EFI_SIMPLE_TEXT_INPUT_PROTOCOL\r
+  which exposes much more state and modifier information from the input device,\r
+  also allows one to register a notification for a particular keystroke.\r
 \r
-  Copyright (c) 2006 - 2008, Intel Corporation \r
+  Copyright (c) 2006 - 2009, Intel Corporation \r
   All rights reserved. This program and the accompanying materials                          \r
   are licensed and made available under the terms and conditions of the BSD License         \r
   which accompanies this distribution.  The full text of the license may be found at        \r
@@ -18,9 +19,6 @@
 #ifndef __SIMPLE_TEXT_IN_EX_H__\r
 #define __SIMPLE_TEXT_IN_EX_H__\r
 \r
-#include <ProcessorBind.h>\r
-#include <Pi/PiMultiPhase.h>\r
-\r
 #define EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL_GUID \\r
   {0xdd9e7534, 0x7762, 0x4698, { 0x8c, 0x14, 0xf5, 0x85, 0x17, 0xa6, 0x25, 0xaa } }\r
 \r
@@ -60,42 +58,38 @@ EFI_STATUS
 );\r
 \r
 \r
-//\r
-// EFI_KEY_TOGGLE_STATE\r
-//\r
+///\r
+/// EFI_KEY_TOGGLE_STATE. The toggle states are defined.\r
+/// They are: EFI_TOGGLE_STATE_VALID, EFI_SCROLL_LOCK_ACTIVE\r
+/// EFI_NUM_LOCK_ACTIVE, EFI_CAPS_LOCK_ACTIVE\r
+///\r
 typedef UINT8 EFI_KEY_TOGGLE_STATE;\r
 \r
-/**\r
-  Definition of EFI_KEY_STATE\r
-\r
-  @param KeyShiftState  Reflects the currently pressed shift\r
-                        modifiers for the input device. The\r
-                        returned value is valid only if the high\r
-                        order bit has been set.\r
-\r
-  @param KeyToggleState Reflects the current internal state of\r
-                        various toggled attributes. The returned\r
-                        value is valid only if the high order\r
-                        bit has been set.\r
-\r
-**/\r
 typedef struct _EFI_KEY_STATE {\r
+  ///\r
+  /// Reflects the currently pressed shift\r
+  /// modifiers for the input device. The\r
+  /// returned value is valid only if the high\r
+  /// order bit has been set.\r
+  ///\r
   UINT32                KeyShiftState;\r
+  ///\r
+  /// Reflects the current internal state of\r
+  /// various toggled attributes. The returned\r
+  /// value is valid only if the high order\r
+  /// bit has been set.\r
+  ///\r
   EFI_KEY_TOGGLE_STATE  KeyToggleState;\r
 } EFI_KEY_STATE;\r
 \r
-/**\r
-  Definition of EFI_KEY_DATA.\r
-\r
-  @param Key      The EFI scan code and Unicode value returned from\r
-                  the input device.\r
-\r
-  @param KeyState The current state of various toggled\r
-                  attributes as well as input modifier values.\r
-\r
-**/\r
 typedef struct {\r
+  ///\r
+  /// The EFI scan code and Unicode value returned from the input device.\r
+  ///\r
   EFI_INPUT_KEY   Key;\r
+  ///\r
+  /// The current state of various toggled attributes as well as input modifier values.\r
+  ///\r
   EFI_KEY_STATE   KeyState;\r
 } EFI_KEY_DATA;\r
 \r
@@ -156,7 +150,7 @@ typedef struct {
   there is no pending keystroke the function returns\r
   EFI_NOT_READY. If there is a pending keystroke, then\r
   KeyData.Key.ScanCode is the EFI scan code defined in Error!\r
-  Reference source not found.. The KeyData.Key.UnicodeChar is the\r
+  Reference source not found. The KeyData.Key.UnicodeChar is the\r
   actual printable character or is zero if the key does not\r
   represent a printable character (control key, function key,\r
   etc.). The KeyData.KeyState is shift state for the character\r
@@ -234,9 +228,9 @@ EFI_STATUS
   IN EFI_KEY_TOGGLE_STATE              *KeyToggleState\r
 );\r
 \r
-//\r
-// EFI_KEY_NOTIFY\r
-//\r
+///\r
+/// The function will be called when the key sequence is typed specified by KeyData.\r
+///\r
 typedef\r
 EFI_STATUS\r
 (EFIAPI *EFI_KEY_NOTIFY_FUNCTION)(\r
@@ -300,34 +294,18 @@ EFI_STATUS
 );\r
 \r
 \r
-/**\r
-  The EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL is used on the ConsoleIn\r
-  device. It is an extension to the Simple Text Input protocol\r
-  which allows a variety of extended shift state information to be\r
-  returned.\r
-\r
-  @param Reset            \r
-  Reset the ConsoleIn device. See Reset().\r
-\r
-  @param ReadKeyStrokeEx  \r
-  Returns the next input character.\r
-\r
-  @param WaitForKeyEx   \r
-  Event to use with WaitForEvent() to wait for a key to be available.\r
-\r
-  @param SetState   \r
-  Set the EFI_KEY_TOGGLE_STATE state settings for the input device.\r
-\r
-  @param RegisterKeyNotify  \r
-  Register a notification function to be called when a given key sequence is hit.\r
-\r
-  @param UnregisterKeyNotifyRemoves   \r
-  A specific notification function.\r
-\r
-**/\r
+///\r
+/// The EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL is used on the ConsoleIn\r
+/// device. It is an extension to the Simple Text Input protocol\r
+/// which allows a variety of extended shift state information to be\r
+/// returned.\r
+///\r
 struct _EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL{\r
   EFI_INPUT_RESET_EX              Reset;\r
   EFI_INPUT_READ_KEY_EX           ReadKeyStrokeEx;\r
+  ///\r
+  /// Event to use with WaitForEvent() to wait for a key to be available.\r
+  ///\r
   EFI_EVENT                       WaitForKeyEx;\r
   EFI_SET_STATE                   SetState;\r
   EFI_REGISTER_KEYSTROKE_NOTIFY   RegisterKeyNotify;\r