ShellPkg: Update comments for functions to clarify buffer origin.

Signed-off-by: darylm503
Reviewed-by: jljusten



git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@12687 6f19259b-4bc3-4df7-8a09-765794883524

1 files changed, 43 insertions, 39 deletions

diff --git a/ShellPkg/Library/UefiFileHandleLib/UefiFileHandleLib.c b/ShellPkg/Library/UefiFileHandleLib/UefiFileHandleLib.c
index 116c78f38b..0e2f93debc 100644
--- a/ShellPkg/Library/UefiFileHandleLib/UefiFileHandleLib.c
+++ b/ShellPkg/Library/UefiFileHandleLib/UefiFileHandleLib.c
@@ -101,20 +101,20 @@ FileHandleGetInfo (
 

   @param[in]  FileInfo          The information to set.

 

-  @retval EFI_SUCCESS		        The information was set.

+  @retval EFI_SUCCESS           The information was set.

   @retval EFI_INVALID_PARAMETER A parameter was out of range or invalid.

   @retval EFI_UNSUPPORTED       The FileHandle does not support FileInfo.

-  @retval EFI_NO_MEDIA		      The device has no medium.

-  @retval EFI_DEVICE_ERROR	    The device reported an error.

-  @retval EFI_VOLUME_CORRUPTED	The file system structures are corrupted.

-  @retval EFI_WRITE_PROTECTED	  The file or medium is write protected.

+  @retval EFI_NO_MEDIA          The device has no medium.

+  @retval EFI_DEVICE_ERROR      The device reported an error.

+  @retval EFI_VOLUME_CORRUPTED  The file system structures are corrupted.

+  @retval EFI_WRITE_PROTECTED   The file or medium is write protected.

   @retval EFI_ACCESS_DENIED     The file was opened read only.

   @retval EFI_VOLUME_FULL       The volume is full.

 **/

 EFI_STATUS

 EFIAPI

 FileHandleSetInfo (

-  IN EFI_FILE_HANDLE  	        FileHandle,

+  IN EFI_FILE_HANDLE            FileHandle,

   IN CONST EFI_FILE_INFO        *FileInfo

   )

 {

@@ -198,14 +198,14 @@ FileHandleRead(
                               the number of bytes written.

   @param Buffer               the buffer containing data to write is stored.

 

- @retval EFI_SUCCESS	        Data was written.

- @retval EFI_UNSUPPORTED	    Writes to an open directory are not supported.

- @retval EFI_NO_MEDIA	        The device has no media.

- @retval EFI_DEVICE_ERROR	    The device reported an error.

- @retval EFI_VOLUME_CORRUPTED	The file system structures are corrupted.

- @retval EFI_WRITE_PROTECTED	The device is write-protected.

- @retval EFI_ACCESS_DENIED	  The file was open for read only.

- @retval EFI_VOLUME_FULL	    The volume is full.

+ @retval EFI_SUCCESS          Data was written.

+ @retval EFI_UNSUPPORTED      Writes to an open directory are not supported.

+ @retval EFI_NO_MEDIA         The device has no media.

+ @retval EFI_DEVICE_ERROR     The device reported an error.

+ @retval EFI_VOLUME_CORRUPTED The file system structures are corrupted.

+ @retval EFI_WRITE_PROTECTED  The device is write-protected.

+ @retval EFI_ACCESS_DENIED    The file was open for read only.

+ @retval EFI_VOLUME_FULL      The volume is full.

 **/

 EFI_STATUS

 EFIAPI

@@ -266,12 +266,12 @@ FileHandleClose (
   @retval EFI_SUCCESS           the file was closed sucessfully

   @retval EFI_WARN_DELETE_FAILURE the handle was closed, but the file was not

                                 deleted

-  @retval INVALID_PARAMETER    	One of the parameters has an invalid value.

+  @retval INVALID_PARAMETER     One of the parameters has an invalid value.

 **/

 EFI_STATUS

 EFIAPI

 FileHandleDelete (

-  IN EFI_FILE_HANDLE		FileHandle

+  IN EFI_FILE_HANDLE    FileHandle

   )

 {

   EFI_STATUS Status;

@@ -308,8 +308,8 @@ FileHandleDelete (
 EFI_STATUS

 EFIAPI

 FileHandleSetPosition (

-  IN EFI_FILE_HANDLE   	FileHandle,

-  IN UINT64           	Position

+  IN EFI_FILE_HANDLE    FileHandle,

+  IN UINT64             Position

   )

 {

   //

@@ -441,15 +441,19 @@ FileHandleIsDirectory (
   return (EFI_SUCCESS);

 }

 

-/**

-  Retrieves the first file from a directory

+/** Retrieve first entry from a directory.

+

+  This function takes an open directory handle and gets information from the

+  first entry in the directory.  A buffer is allocated to contain

+  the information and a pointer to the buffer is returned in *Buffer.  The

+  caller can use FileHandleFindNextFile() to get subsequent directory entries.

 

-  This function opens a directory and gets the first file's info in the

-  directory. Caller can use FileHandleFindNextFile() to get other files.  When

-  complete the caller is responsible for calling FreePool() on Buffer.

+  The buffer will be freed by FileHandleFindNextFile() when the last directory

+  entry is read.  Otherwise, the caller must free the buffer, using FreePool,

+  when finished with it.

 

-  @param DirHandle              The file handle of the directory to search

-  @param Buffer                 Pointer to buffer for file's information

+  @param[in]  DirHandle         The file handle of the directory to search.

+  @param[out] Buffer            The pointer to pointer to buffer for file's information.

 

   @retval EFI_SUCCESS           Found the first file.

   @retval EFI_NOT_FOUND         Cannot find the directory.

@@ -512,19 +516,19 @@ FileHandleFindFirstFile (
   }

   return (EFI_SUCCESS);

 }

-/**

-  Retrieves the next file in a directory.

 

-  To use this function, caller must call the FileHandleFindFirstFile() to get the

-  first file, and then use this function get other files. This function can be

-  called for several times to get each file's information in the directory. If

-  the call of FileHandleFindNextFile() got the last file in the directory, the next

-  call of this function has no file to get. *NoFile will be set to TRUE and the

-  Buffer memory will be automatically freed.

+/** Retrieve next entries from a directory.

+

+  To use this function, the caller must first call the FileHandleFindFirstFile()

+  function to get the first directory entry.  Subsequent directory entries are

+  retrieved by using the FileHandleFindNextFile() function.  This function can

+  be called several times to get each entry from the directory.  If the call of

+  FileHandleFindNextFile() retrieved the last directory entry, the next call of

+  this function will set *NoFile to TRUE and free the buffer.

 

-  @param DirHandle              the file handle of the directory

-  @param Buffer			            pointer to buffer for file's information

-  @param NoFile			            pointer to boolean when last file is found

+  @param[in]  DirHandle         The file handle of the directory.

+  @param[out] Buffer            The pointer to buffer for file's information.

+  @param[out] NoFile            The pointer to boolean when last file is found.

 

   @retval EFI_SUCCESS           Found the next file, or reached last file

   @retval EFI_NO_MEDIA          The device has no media.

@@ -534,9 +538,9 @@ FileHandleFindFirstFile (
 EFI_STATUS

 EFIAPI

 FileHandleFindNextFile(

-  IN EFI_FILE_HANDLE             DirHandle,

-  OUT EFI_FILE_INFO              *Buffer,

-  OUT BOOLEAN                    *NoFile

+  IN EFI_FILE_HANDLE          DirHandle,

+  OUT EFI_FILE_INFO          *Buffer,

+  OUT BOOLEAN                *NoFile

   )

 {

   EFI_STATUS    Status;