ShellPkg: Add function comments and refine code format to follow EDKII coding style.

Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Qiu Shumin <shumin.qiu@intel.com>
Reviewed-by: Ruiyu Ni <ruiyu.ni@intel.com>
git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@18186 6f19259b-4bc3-4df7-8a09-765794883524

diff --git a/ShellPkg/Library/UefiShellTftpCommandLib/Tftp.c b/ShellPkg/Library/UefiShellTftpCommandLib/Tftp.c
index b872afdb8952ac4611aeb192374eaa55f2125ac5..d8374850fb914d08cf1f7deb3c80a00a155e8f23 100644 (file)
--- a/ShellPkg/Library/UefiShellTftpCommandLib/Tftp.c
+++ b/ShellPkg/Library/UefiShellTftpCommandLib/Tftp.c
@@ -36,18 +36,69 @@ STATIC CONST CHAR16 mTftpProgressFrame[] = L"[
 // (TFTP_PROGRESS_MESSAGE_SIZE-1) '\b'\r
 STATIC CONST CHAR16 mTftpProgressDelete[] = L"\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b\b";\r
 \r
-STATIC BOOLEAN StringToUint16 (\r
+/**\r
+  Check and convert the UINT16 option values of the 'tftp' command\r
+\r
+  @param[in]  ValueStr  Value as an Unicode encoded string\r
+  @param[out] Value     UINT16 value\r
+\r
+  @return     TRUE      The value was returned.\r
+  @return     FALSE     A parsing error occured.\r
+**/\r
+STATIC \r
+BOOLEAN \r
+StringToUint16 (\r
   IN   CONST CHAR16  *ValueStr,\r
   OUT  UINT16        *Value\r
   );\r
 \r
-STATIC EFI_STATUS GetNicName (\r
+/**\r
+  Get the name of the NIC.\r
+\r
+  @param[in]   ControllerHandle  The network physical device handle.\r
+  @param[in]   NicNumber         The network physical device number.\r
+  @param[out]  NicName           Address where to store the NIC name.\r
+                                 The memory area has to be at least\r
+                                 IP4_NIC_NAME_LENGTH bytes wide.\r
+\r
+  @return  EFI_SUCCESS  The name of the NIC was returned.\r
+  @return  Others       The creation of the child for the Managed\r
+                        Network Service failed or the opening of\r
+                        the Managed Network Protocol failed or\r
+                        the operational parameters for the\r
+                        Managed Network Protocol could not be\r
+                        read.\r
+**/\r
+STATIC \r
+EFI_STATUS \r
+GetNicName (\r
   IN   EFI_HANDLE  ControllerHandle,\r
   IN   UINTN       Index,\r
   OUT  CHAR16      *NicName\r
   );\r
 \r
-STATIC EFI_STATUS CreateServiceChildAndOpenProtocol (\r
+/**\r
+  Create a child for the service identified by its service binding protocol GUID\r
+  and get from the child the interface of the protocol identified by its GUID.\r
+\r
+  @param[in]   ControllerHandle            Controller handle.\r
+  @param[in]   ServiceBindingProtocolGuid  Service binding protocol GUID of the\r
+                                           service to be created.\r
+  @param[in]   ProtocolGuid                GUID of the protocol to be open.\r
+  @param[out]  ChildHandle                 Address where the handler of the\r
+                                           created child is returned. NULL is\r
+                                           returned in case of error.\r
+  @param[out]  Interface                   Address where a pointer to the\r
+                                           protocol interface is returned in\r
+                                           case of success.\r
+\r
+  @return  EFI_SUCCESS  The child was created and the protocol opened.\r
+  @return  Others       Either the creation of the child or the opening\r
+                        of the protocol failed.\r
+**/\r
+STATIC \r
+EFI_STATUS \r
+CreateServiceChildAndOpenProtocol (\r
   IN   EFI_HANDLE  ControllerHandle,\r
   IN   EFI_GUID    *ServiceBindingProtocolGuid,\r
   IN   EFI_GUID    *ProtocolGuid,\r
@@ -55,20 +106,71 @@ STATIC EFI_STATUS CreateServiceChildAndOpenProtocol (
   OUT  VOID        **Interface\r
   );\r
 \r
-STATIC VOID CloseProtocolAndDestroyServiceChild (\r
+/**\r
+  Close the protocol identified by its GUID on the child handle of the service\r
+  identified by its service binding protocol GUID, then destroy the child\r
+  handle.\r
+\r
+  @param[in]  ControllerHandle            Controller handle.\r
+  @param[in]  ServiceBindingProtocolGuid  Service binding protocol GUID of the\r
+                                          service to be destroyed.\r
+  @param[in]  ProtocolGuid                GUID of the protocol to be closed.\r
+  @param[in]  ChildHandle                 Handle of the child to be destroyed.\r
+\r
+**/\r
+STATIC \r
+VOID \r
+CloseProtocolAndDestroyServiceChild (\r
   IN  EFI_HANDLE  ControllerHandle,\r
   IN  EFI_GUID    *ServiceBindingProtocolGuid,\r
   IN  EFI_GUID    *ProtocolGuid,\r
   IN  EFI_HANDLE  ChildHandle\r
   );\r
 \r
-STATIC EFI_STATUS GetFileSize (\r
+/**\r
+  Worker function that gets the size in numbers of bytes of a file from a TFTP\r
+  server before to download the file.\r
+\r
+  @param[in]   Mtftp4    MTFTP4 protocol interface\r
+  @param[in]   FilePath  Path of the file, ASCII encoded\r
+  @param[out]  FileSize  Address where to store the file size in number of\r
+                         bytes.\r
+\r
+  @retval  EFI_SUCCESS      The size of the file was returned.\r
+  @retval  EFI_UNSUPPORTED  The server does not support the "tsize" option.\r
+  @retval  Others           Error when retrieving the information from the server\r
+                            (see EFI_MTFTP4_PROTOCOL.GetInfo() status codes)\r
+                            or error when parsing the response of the server.\r
+**/\r
+STATIC \r
+EFI_STATUS \r
+GetFileSize (\r
   IN   EFI_MTFTP4_PROTOCOL  *Mtftp4,\r
   IN   CONST CHAR8          *FilePath,\r
   OUT  UINTN                *FileSize\r
   );\r
 \r
-STATIC EFI_STATUS DownloadFile (\r
+/**\r
+  Worker function that download the data of a file from a TFTP server given\r
+  the path of the file and its size.\r
+\r
+  @param[in]   Mtftp4         MTFTP4 protocol interface\r
+  @param[in]   FilePath       Path of the file, Unicode encoded\r
+  @param[in]   AsciiFilePath  Path of the file, ASCII encoded\r
+  @param[in]   FileSize       Size of the file in number of bytes\r
+  @param[out]  Data           Address where to store the address of the buffer\r
+                              where the data of the file were downloaded in\r
+                              case of success.\r
+\r
+  @retval  EFI_SUCCESS           The file was downloaded.\r
+  @retval  EFI_OUT_OF_RESOURCES  A memory allocation failed.\r
+  @retval  Others                The downloading of the file from the server failed\r
+                                 (see EFI_MTFTP4_PROTOCOL.ReadFile() status codes).\r
+\r
+**/\r
+STATIC \r
+EFI_STATUS \r
+DownloadFile (\r
   IN   EFI_MTFTP4_PROTOCOL  *Mtftp4,\r
   IN   CONST CHAR16         *FilePath,\r
   IN   CONST CHAR8          *AsciiFilePath,\r
@@ -76,7 +178,21 @@ STATIC EFI_STATUS DownloadFile (
   OUT  VOID                 **Data\r
   );\r
 \r
-STATIC EFI_STATUS CheckPacket (\r
+/**\r
+  Update the progress of a file download\r
+  This procedure is called each time a new TFTP packet is received.\r
+\r
+  @param[in]  This       MTFTP4 protocol interface\r
+  @param[in]  Token      Parameters for the download of the file\r
+  @param[in]  PacketLen  Length of the packet\r
+  @param[in]  Packet     Address of the packet\r
+\r
+  @retval  EFI_SUCCESS  All packets are accepted.\r
+\r
+**/\r
+STATIC \r
+EFI_STATUS \r
+CheckPacket (\r
   IN EFI_MTFTP4_PROTOCOL  *This,\r
   IN EFI_MTFTP4_TOKEN     *Token,\r
   IN UINT16               PacketLen,\r