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

2 files changed, 25 insertions, 31 deletions

diff --git a/MdePkg/Include/Library/FileHandleLib.h b/MdePkg/Include/Library/FileHandleLib.h
index ed4d636fdd..bfcf8a4ee3 100644
--- a/MdePkg/Include/Library/FileHandleLib.h
+++ b/MdePkg/Include/Library/FileHandleLib.h
@@ -316,17 +316,16 @@ FileHandleFindNextFile(
 /**

   Retrieve the size of a file.

 

-  If FileHandle is NULL then ASSERT().

-  If Size is NULL then ASSERT().

-

   This function extracts the file size info from the FileHandle's EFI_FILE_INFO

   data.

 

   @param[in] FileHandle         The file handle from which size is retrieved.

   @param[out] Size              The pointer to size.

 

-  @retval EFI_SUCCESS           The operation completed successfully.

+  @retval EFI_SUCCESS           Operation was completed sucessfully.

   @retval EFI_DEVICE_ERROR      Cannot access the file.

+  @retval EFI_INVALID_PARAMETER FileHandle is NULL.

+                                Size is NULL.

 **/

 EFI_STATUS

 EFIAPI

@@ -338,8 +337,6 @@ FileHandleGetSize (
 /**

   Set the size of a file.

 

-  If FileHandle is NULL then ASSERT().

-

   This function changes the file size info from the FileHandle's EFI_FILE_INFO

   data.

 

@@ -348,6 +345,7 @@ FileHandleGetSize (
 

   @retval EFI_SUCCESS           The operation completed successfully.

   @retval EFI_DEVICE_ERROR      Cannot access the file.

+  @retval EFI_INVALID_PARAMETER FileHandle is NULL.

 **/

 EFI_STATUS

 EFIAPI

@@ -437,14 +435,13 @@ FileHandleReturnLine(
 /**

   Function to write a line of unicode text to a file.

 

-  If Handle is NULL, ASSERT.

-

   @param[in]     Handle         FileHandle to write to.

   @param[in]     Buffer         Buffer to write, if NULL the function will

                                 take no action and return EFI_SUCCESS.

 

-  @retval  EFI_SUCCESS          The data was written.

-  @retval  other                Failure.

+  @retval  EFI_SUCCESS            The data was written.

+                                  Buffer is NULL.

+  @retval  EFI_INVALID_PARAMETER  Handle is NULL.

 

   @sa FileHandleWrite

 **/

diff --git a/MdePkg/Library/UefiFileHandleLib/UefiFileHandleLib.c b/MdePkg/Library/UefiFileHandleLib/UefiFileHandleLib.c
index a9d7376cd4..e1f3e89b8c 100644
--- a/MdePkg/Library/UefiFileHandleLib/UefiFileHandleLib.c
+++ b/MdePkg/Library/UefiFileHandleLib/UefiFileHandleLib.c
@@ -575,17 +575,16 @@ FileHandleFindNextFile(
 /**

   Retrieve the size of a file.

 

-  if FileHandle is NULL then return error

-  if Size is NULL then return error

-

   This function extracts the file size info from the FileHandle's EFI_FILE_INFO

   data.

 

-  @param FileHandle             file handle from which size is retrieved

-  @param Size                   pointer to size

+  @param[in] FileHandle         The file handle from which size is retrieved.

+  @param[out] Size              The pointer to size.

 

-  @retval EFI_SUCCESS           operation was completed sucessfully

-  @retval EFI_DEVICE_ERROR      cannot access the file

+  @retval EFI_SUCCESS           Operation was completed sucessfully.

+  @retval EFI_DEVICE_ERROR      Cannot access the file.

+  @retval EFI_INVALID_PARAMETER FileHandle is NULL.

+                                Size is NULL.

 **/

 EFI_STATUS

 EFIAPI

@@ -624,16 +623,15 @@ FileHandleGetSize (
 /**

   Set the size of a file.

 

-  If FileHandle is NULL then return error.

-

   This function changes the file size info from the FileHandle's EFI_FILE_INFO

   data.

 

-  @param FileHandle             File handle whose size is to be changed.

-  @param Size                   New size.

+  @param[in] FileHandle         The file handle whose size is to be changed.

+  @param[in] Size               The new size.

 

-  @retval EFI_SUCCESS           operation was completed sucessfully.

-  @retval EFI_DEVICE_ERROR      cannot access the file.

+  @retval EFI_SUCCESS           The operation completed successfully.

+  @retval EFI_DEVICE_ERROR      Cannot access the file.

+  @retval EFI_INVALID_PARAMETER FileHandle is NULL.

 **/

 EFI_STATUS

 EFIAPI

@@ -1016,16 +1014,15 @@ FileHandleReadLine(
 }

 

 /**

-  function to write a line of unicode text to a file.

-

-  if Handle is NULL, return error.

-  if Buffer is NULL, do nothing.  (return SUCCESS)

+  Function to write a line of unicode text to a file.

 

-  @param[in]     Handle         FileHandle to write to

-  @param[in]     Buffer         Buffer to write

+  @param[in]     Handle         FileHandle to write to.

+  @param[in]     Buffer         Buffer to write, if NULL the function will

+                                take no action and return EFI_SUCCESS.

 

-  @retval  EFI_SUCCESS          the data was written.

-  @retval  other                failure.

+  @retval  EFI_SUCCESS            The data was written.

+                                  Buffer is NULL.

+  @retval  EFI_INVALID_PARAMETER  Handle is NULL.

 

   @sa FileHandleWrite

 **/