Reviewed the code comments in the Include/Protocol directory for typos, grammar issue...

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

diff --git a/MdePkg/Include/Protocol/Mtftp4.h b/MdePkg/Include/Protocol/Mtftp4.h
index f2c3084b8877f48d3da84f139a64f9cbecdd2622..149c6270e01eba5df7b1063d5a74c7d11020da4f 100644 (file)
--- a/MdePkg/Include/Protocol/Mtftp4.h
+++ b/MdePkg/Include/Protocol/Mtftp4.h
@@ -98,14 +98,41 @@ typedef struct {
 } EFI_MTFTP4_ERROR_HEADER;\r
 \r
 typedef union {\r
+  ///\r
+  /// Type of packets as defined by the MTFTPv4 packet opcodes.\r
+  ///\r
   UINT16                  OpCode;\r
+  ///\r
+  /// Read request packet header.\r
+  ///\r
   EFI_MTFTP4_REQ_HEADER   Rrq;\r
+  ///\r
+  /// Write request packet header.\r
+  ///\r
   EFI_MTFTP4_REQ_HEADER   Wrq;\r
+  ///\r
+  /// Option acknowledge packet header.\r
+  ///\r
   EFI_MTFTP4_OACK_HEADER  Oack;\r
+  ///\r
+  /// Data packet header.\r
+  ///\r
   EFI_MTFTP4_DATA_HEADER  Data;\r
+  ///\r
+  /// Acknowledgement packet header.\r
+  ///\r
   EFI_MTFTP4_ACK_HEADER   Ack;\r
+  ///\r
+  /// Data packet header with big block number.\r
+  ///\r
   EFI_MTFTP4_DATA8_HEADER Data8;\r
+  ///\r
+  /// Acknowledgement header with big block num.\r
+  ///\r
   EFI_MTFTP4_ACK8_HEADER  Ack8;\r
+  ///\r
+  /// Error packet header.\r
+  ///\r
   EFI_MTFTP4_ERROR_HEADER Error;\r
 } EFI_MTFTP4_PACKET;\r
 \r
@@ -155,9 +182,9 @@ typedef struct {
 //\r
 \r
 /**\r
-  a callback function that is provided by the caller to intercept               \r
+  A callback function that is provided by the caller to intercept               \r
   the EFI_MTFTP4_OPCODE_DATA or EFI_MTFTP4_OPCODE_DATA8 packets processed in the\r
-  EFI_MTFTP4_PROTOCOL.ReadFile() function, and alternatively to intercept       \r
+  EFI_MTFTP4_PROTOCOL.ReadFile() function, or alternatively to intercept       \r
   EFI_MTFTP4_OPCODE_OACK or EFI_MTFTP4_OPCODE_ERROR packets during a call to    \r
   EFI_MTFTP4_PROTOCOL.ReadFile(), WriteFile() or ReadDirectory().                   \r
 \r
@@ -203,7 +230,7 @@ EFI_STATUS
   );\r
 \r
 /**\r
-  a callback function that the caller provides to feed data to the\r
+  A callback function that the caller provides to feed data to the\r
   EFI_MTFTP4_PROTOCOL.WriteFile() function.\r
 \r
   @param  This   Pointer to the EFI_MTFTP4_PROTOCOL instance.\r
@@ -477,17 +504,60 @@ struct _EFI_MTFTP4_PROTOCOL {
 };\r
 \r
 struct _EFI_MTFTP4_TOKEN {\r
+  ///\r
+  /// The status that is returned to the caller at the end of the operation\r
+  /// to indicate whether this operation completed successfully.\r
+  ///\r
   EFI_STATUS                  Status;\r
+  ///\r
+  /// The event that will be signaled when the operation completes. If\r
+  /// set to NULL, the corresponding function will wait until the read or\r
+  /// write operation finishes. The type of Event must be\r
+  /// EVT_NOTIFY_SIGNAL. The Task Priority Level (TPL) of\r
+  /// Event must be lower than or equal to TPL_CALLBACK.\r
+  ///\r
   EFI_EVENT                   Event;\r
+  ///\r
+  /// If not NULL, the data that will be used to override the existing configure data.\r
+  ///\r
   EFI_MTFTP4_OVERRIDE_DATA    *OverrideData;\r
+  ///\r
+  /// Pointer to the ASCIIZ file name string.\r
+  ///\r
   UINT8                       *Filename;\r
+  ///\r
+  /// Pointer to the ASCIIZ mode string. If NULL, "octet" is used.\r
+  ///\r
   UINT8                       *ModeStr;\r
+  ///\r
+  /// Number of option/value string pairs.\r
+  ///\r
   UINT32                      OptionCount;\r
+  ///\r
+  /// Pointer to an array of option/value string pairs. Ignored if OptionCount is zero.\r
+  ///\r
   EFI_MTFTP4_OPTION           *OptionList;\r
+  ///\r
+  /// Size of the data buffer.\r
+  ///\r
   OUT UINT64                  BufferSize;\r
+  ///\r
+  /// Pointer to the data buffer. Data that is downloaded from the\r
+  /// MTFTPv4 server is stored here. Data that is uploaded to the\r
+  /// MTFTPv4 server is read from here. Ignored if BufferSize is zero.\r
+  ///\r
   OUT VOID                    *Buffer;\r
+  ///\r
+  /// Pointer to the callback function to check the contents of the received packet.\r
+  ///\r
   EFI_MTFTP4_CHECK_PACKET     CheckPacket;\r
+  ///\r
+  /// Pointer to the function to be called when a timeout occurs.\r
+  ///\r
   EFI_MTFTP4_TIMEOUT_CALLBACK TimeoutCallback;\r
+  ///\r
+  /// Pointer to the function to provide the needed packet contents.\r
+  ///\r
   EFI_MTFTP4_PACKET_NEEDED    PacketNeeded;\r
 };\r
 \r