MdePkg: Refine the comments for FileHandleLib.

Make the function comments of FileHandleLib consistent with instance implementation.

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

diff --git a/MdePkg/Include/Library/FileHandleLib.h b/MdePkg/Include/Library/FileHandleLib.h
index ed4d636fdd54da47544aecc828bf515d142dfe86..bfcf8a4ee3f997169780d471f9d05eace5988e27 100644 (file)
--- a/MdePkg/Include/Library/FileHandleLib.h
+++ b/MdePkg/Include/Library/FileHandleLib.h
@@ -316,17 +316,16 @@ FileHandleFindNextFile(
 /**\r
   Retrieve the size of a file.\r
 \r
-  If FileHandle is NULL then ASSERT().\r
-  If Size is NULL then ASSERT().\r
-\r
   This function extracts the file size info from the FileHandle's EFI_FILE_INFO\r
   data.\r
 \r
   @param[in] FileHandle         The file handle from which size is retrieved.\r
   @param[out] Size              The pointer to size.\r
 \r
-  @retval EFI_SUCCESS           The operation completed successfully.\r
+  @retval EFI_SUCCESS           Operation was completed sucessfully.\r
   @retval EFI_DEVICE_ERROR      Cannot access the file.\r
+  @retval EFI_INVALID_PARAMETER FileHandle is NULL.\r
+                                Size is NULL.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -338,8 +337,6 @@ FileHandleGetSize (
 /**\r
   Set the size of a file.\r
 \r
-  If FileHandle is NULL then ASSERT().\r
-\r
   This function changes the file size info from the FileHandle's EFI_FILE_INFO\r
   data.\r
 \r
@@ -348,6 +345,7 @@ FileHandleGetSize (
 \r
   @retval EFI_SUCCESS           The operation completed successfully.\r
   @retval EFI_DEVICE_ERROR      Cannot access the file.\r
+  @retval EFI_INVALID_PARAMETER FileHandle is NULL.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -437,14 +435,13 @@ FileHandleReturnLine(
 /**\r
   Function to write a line of unicode text to a file.\r
 \r
-  If Handle is NULL, ASSERT.\r
-\r
   @param[in]     Handle         FileHandle to write to.\r
   @param[in]     Buffer         Buffer to write, if NULL the function will\r
                                 take no action and return EFI_SUCCESS.\r
 \r
-  @retval  EFI_SUCCESS          The data was written.\r
-  @retval  other                Failure.\r
+  @retval  EFI_SUCCESS            The data was written.\r
+                                  Buffer is NULL.\r
+  @retval  EFI_INVALID_PARAMETER  Handle is NULL.\r
 \r
   @sa FileHandleWrite\r
 **/\r

diff --git a/MdePkg/Library/UefiFileHandleLib/UefiFileHandleLib.c b/MdePkg/Library/UefiFileHandleLib/UefiFileHandleLib.c
index a9d7376cd4383d861341944cbc1b8dfdad48ae82..e1f3e89b8c80d89786456c7cadac78c45a9d4d6e 100644 (file)
--- a/MdePkg/Library/UefiFileHandleLib/UefiFileHandleLib.c
+++ b/MdePkg/Library/UefiFileHandleLib/UefiFileHandleLib.c
@@ -575,17 +575,16 @@ FileHandleFindNextFile(
 /**\r
   Retrieve the size of a file.\r
 \r
-  if FileHandle is NULL then return error\r
-  if Size is NULL then return error\r
-\r
   This function extracts the file size info from the FileHandle's EFI_FILE_INFO\r
   data.\r
 \r
-  @param FileHandle             file handle from which size is retrieved\r
-  @param Size                   pointer to size\r
+  @param[in] FileHandle         The file handle from which size is retrieved.\r
+  @param[out] Size              The pointer to size.\r
 \r
-  @retval EFI_SUCCESS           operation was completed sucessfully\r
-  @retval EFI_DEVICE_ERROR      cannot access the file\r
+  @retval EFI_SUCCESS           Operation was completed sucessfully.\r
+  @retval EFI_DEVICE_ERROR      Cannot access the file.\r
+  @retval EFI_INVALID_PARAMETER FileHandle is NULL.\r
+                                Size is NULL.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -624,16 +623,15 @@ FileHandleGetSize (
 /**\r
   Set the size of a file.\r
 \r
-  If FileHandle is NULL then return error.\r
-\r
   This function changes the file size info from the FileHandle's EFI_FILE_INFO\r
   data.\r
 \r
-  @param FileHandle             File handle whose size is to be changed.\r
-  @param Size                   New size.\r
+  @param[in] FileHandle         The file handle whose size is to be changed.\r
+  @param[in] Size               The new size.\r
 \r
-  @retval EFI_SUCCESS           operation was completed sucessfully.\r
-  @retval EFI_DEVICE_ERROR      cannot access the file.\r
+  @retval EFI_SUCCESS           The operation completed successfully.\r
+  @retval EFI_DEVICE_ERROR      Cannot access the file.\r
+  @retval EFI_INVALID_PARAMETER FileHandle is NULL.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
@@ -1016,16 +1014,15 @@ FileHandleReadLine(
 }\r
 \r
 /**\r
-  function to write a line of unicode text to a file.\r
-\r
-  if Handle is NULL, return error.\r
-  if Buffer is NULL, do nothing.  (return SUCCESS)\r
+  Function to write a line of unicode text to a file.\r
 \r
-  @param[in]     Handle         FileHandle to write to\r
-  @param[in]     Buffer         Buffer to write\r
+  @param[in]     Handle         FileHandle to write to.\r
+  @param[in]     Buffer         Buffer to write, if NULL the function will\r
+                                take no action and return EFI_SUCCESS.\r
 \r
-  @retval  EFI_SUCCESS          the data was written.\r
-  @retval  other                failure.\r
+  @retval  EFI_SUCCESS            The data was written.\r
+                                  Buffer is NULL.\r
+  @retval  EFI_INVALID_PARAMETER  Handle is NULL.\r
 \r
   @sa FileHandleWrite\r
 **/\r