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

ShellPkg/Include/Library/FileHandleLib.h

@@ -259,12 +259,16 @@ FileHandleIsDirectory (
   IN EFI_FILE_HANDLE            DirHandle
   );
 
-/**
+/** Retrieve first entry from a directory.
-  Retrieves the first file from a directory.
 
-  This function opens a directory and gets the first file's information in the
+  This function takes an open directory handle and gets information from the
-  directory. The caller the uses FileHandleFindNextFile() to get other files.  When
+  first entry in the directory.  A buffer is allocated to contain
-  complete, the caller is responsible for calling FreePool() on *Buffer.
+  the information and a pointer to the buffer is returned in *Buffer.  The
+  caller can use FileHandleFindNextFile() to get subsequent directory entries.
+
+  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[in]  DirHandle         The file handle of the directory to search.
   @param[out] Buffer            The pointer to pointer to buffer for file's information.
@@ -283,15 +287,15 @@ FileHandleFindFirstFile (
   IN EFI_FILE_HANDLE            DirHandle,
   OUT EFI_FILE_INFO             **Buffer
   );
-/**
-  Retrieves the next file in a directory.
 
-  To use this function, caller must call the FileHandleFindFirstFile() to get the
+/** Retrieve next entries from a directory.
-  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
+  To use this function, the caller must first call the FileHandleFindFirstFile()
-  the call of FileHandleFindNextFile() got the last file in the directory, the next
+  function to get the first directory entry.  Subsequent directory entries are
-  call of this function has no file to get. *NoFile will be set to TRUE and the
+  retrieved by using the FileHandleFindNextFile() function.  This function can
-  Buffer memory will be automatically freed.
+  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[in]  DirHandle         The file handle of the directory.
   @param[out] Buffer            The pointer to buffer for file's information.

ShellPkg/Include/Library/ShellLib.h

@@ -366,14 +366,16 @@ ShellFlushFile (
   IN SHELL_FILE_HANDLE          FileHandle
   );
 
-/**
+/** Retrieve first entry from a directory.
-  Retrieves the first file from a directory
 
-  This function takes an open directory handle and gets the first file
+  This function takes an open directory handle and gets information from the
-  in the directory's info. Caller can use ShellFindNextFile() to get
+  first entry in the directory.  A buffer is allocated to contain
-  subsequent files.
+  the information and a pointer to the buffer is returned in *Buffer.  The
+  caller can use ShellFindNextFile() to get subsequent directory entries.
 
-  Caller must use FreePool on *Buffer opon completion of all file searching.
+  The buffer will be freed by ShellFindNextFile() when the last directory
+  entry is read.  Otherwise, the caller must free the buffer, using FreePool,
+  when finished with it.
 
   @param[in]  DirHandle         The file handle of the directory to search.
   @param[out] Buffer            The pointer to the buffer for the file's information.
@@ -383,6 +385,9 @@ ShellFlushFile (
   @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.
+  @return Others                Status of ShellGetFileInfo, ShellSetFilePosition,
+                                or ShellReadFile.
+
   @sa ShellReadFile
 **/
 EFI_STATUS
@@ -392,24 +397,24 @@ ShellFindFirstFile (
      OUT  EFI_FILE_INFO         **Buffer
   );
 
-/**
+/** Retrieve next entries from a directory.
-  Retrieves the next file in a directory.
 
-  To use this function, caller must call the ShellFindFirstFile() to get the
+  To use this function, the caller must first call the ShellFindFirstFile()
-  first file, and then use this function get other files. This function can be
+  function to get the first directory entry.  Subsequent directory entries are
-  called for several times to get each file's information in the directory. If
+  retrieved by using the ShellFindNextFile() function.  This function can
-  the call of ShellFindNextFile() got the last file in the directory, the next
+  be called several times to get each entry from the directory.  If the call of
-  call of this function has no file to get. *NoFile will be set to TRUE, and the
+  ShellFindNextFile() retrieved the last directory entry, the next call of
-  data in Buffer is meaningless.
+  this function will set *NoFile to TRUE and free the buffer.
 
   @param[in]  DirHandle         The file handle of the directory.
-  @param[in, out] Buffer         The pointer to buffer for file's information.
+  @param[out] Buffer            The pointer to buffer for file's information.
-  @param[in, out] NoFile         The pointer to boolean when last file is found.
+  @param[out] NoFile            The pointer to boolean when last file is found.
 
   @retval EFI_SUCCESS           Found the next file.
   @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.
+
   @sa ShellReadFile
 **/
 EFI_STATUS

ShellPkg/Library/UefiFileHandleLib/UefiFileHandleLib.c

@@ -441,15 +441,19 @@ FileHandleIsDirectory (
   return (EFI_SUCCESS);
 }
 
-/**
+/** Retrieve first entry from a directory.
-  Retrieves the first file from a directory
 
-  This function opens a directory and gets the first file's info in the
+  This function takes an open directory handle and gets information from the
-  directory. Caller can use FileHandleFindNextFile() to get other files.  When
+  first entry in the directory.  A buffer is allocated to contain
-  complete the caller is responsible for calling FreePool() on Buffer.
+  the information and a pointer to the buffer is returned in *Buffer.  The
+  caller can use FileHandleFindNextFile() to get subsequent directory entries.
 
-  @param DirHandle              The file handle of the directory to search
+  The buffer will be freed by FileHandleFindNextFile() when the last directory
-  @param Buffer                 Pointer to buffer for file's information
+  entry is read.  Otherwise, the caller must free the buffer, using FreePool,
+  when finished with it.
+
+  @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
+/** Retrieve next entries from a directory.
-  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.
 
-  @param DirHandle              the file handle of the directory
+  To use this function, the caller must first call the FileHandleFindFirstFile()
-  @param Buffer			            pointer to buffer for file's information
+  function to get the first directory entry.  Subsequent directory entries are
-  @param NoFile			            pointer to boolean when last file is found
+  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[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.

ShellPkg/Library/UefiShellLib/UefiShellLib.c

@@ -932,15 +932,19 @@ ShellFlushFile (
   return (FileFunctionMap.FlushFile(FileHandle));
 }
 
-/**
+/** Retrieve first entry from a directory.
-  Retrieves the first file from a directory
 
-  This function opens a directory and gets the first file's info in the
+  This function takes an open directory handle and gets information from the
-  directory. Caller can use ShellFindNextFile() to get other files.  When
+  first entry in the directory.  A buffer is allocated to contain
-  complete the caller is responsible for calling FreePool() on Buffer.
+  the information and a pointer to the buffer is returned in *Buffer.  The
+  caller can use ShellFindNextFile() to get subsequent directory entries.
 
-  @param DirHandle              The file handle of the directory to search
+  The buffer will be freed by ShellFindNextFile() when the last directory
-  @param Buffer                 Pointer to buffer for file's information
+  entry is read.  Otherwise, the caller must free the buffer, using FreePool,
+  when finished with it.
+
+  @param[in]  DirHandle         The file handle of the directory to search.
+  @param[out] Buffer            The pointer to the buffer for the file's information.
 
   @retval EFI_SUCCESS           Found the first file.
   @retval EFI_NOT_FOUND         Cannot find the directory.
@@ -962,19 +966,18 @@ ShellFindFirstFile (
   //
   return (FileHandleFindFirstFile(DirHandle, Buffer));
 }
-/**
+/** Retrieve next entries from a directory.
-  Retrieves the next file in a directory.
 
-  To use this function, caller must call the ShellFindFirstFile() to get the
+  To use this function, the caller must first call the ShellFindFirstFile()
-  first file, and then use this function get other files. This function can be
+  function to get the first directory entry.  Subsequent directory entries are
-  called for several times to get each file's information in the directory. If
+  retrieved by using the ShellFindNextFile() function.  This function can
-  the call of ShellFindNextFile() got the last file in the directory, the next
+  be called several times to get each entry from the directory.  If the call of
-  call of this function has no file to get. *NoFile will be set to TRUE and the
+  ShellFindNextFile() retrieved the last directory entry, the next call of
-  Buffer memory will be automatically freed.
+  this function will set *NoFile to TRUE and free the buffer.
 
-  @param DirHandle              the file handle of the directory
+  @param[in]  DirHandle         The file handle of the directory.
-  @param Buffer			            pointer to buffer for file's information
+  @param[out] Buffer            The pointer to buffer for file's information.
-  @param NoFile			            pointer to boolean when last file is found
+  @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.