[patch] MdePkg/HiiImageEx: Fix incorrect comments of functions

* [patch] MdePkg/HiiImageEx: Fix incorrect comments of functions
@ 2017-03-14  1:39 Dandan Bi
  2017-03-14  1:39 ` [patch] ShellPkg/UefiShellBcfgCommandLib: Fix VS2012 build failure Dandan Bi
                   ` (2 more replies)
  0 siblings, 3 replies; 9+ messages in thread
From: Dandan Bi @ 2017-03-14  1:39 UTC (permalink / raw)
  To: edk2-devel; +Cc: Liming Gao, Ruiyu Ni, Eric Dong

Cc: Liming Gao <liming.gao@intel.com>
Cc: Ruiyu Ni <ruiyu.ni@intel.com>
Cc: Eric Dong <eric.dong@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.0
Signed-off-by: Dandan Bi <dandan.bi@intel.com>
---
 MdePkg/Include/Protocol/HiiImageEx.h | 80 +++++++++++++++++++-----------------
 1 file changed, 43 insertions(+), 37 deletions(-)

diff --git a/MdePkg/Include/Protocol/HiiImageEx.h b/MdePkg/Include/Protocol/HiiImageEx.h
index b92fc3a..5a48380 100644
--- a/MdePkg/Include/Protocol/HiiImageEx.h
+++ b/MdePkg/Include/Protocol/HiiImageEx.h
@@ -26,12 +26,11 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 
 typedef struct _EFI_HII_IMAGE_EX_PROTOCOL EFI_HII_IMAGE_EX_PROTOCOL;
 
 /**
   The prototype of this extension function is the same with EFI_HII_IMAGE_PROTOCOL.NewImage().
-  Same with EFI_HII_IMAGE_PROTOCOL.NewImage().This protocol invokes
-EFI_HII_IMAGE_PROTOCOL.NewImage() implicitly.
+  This protocol invokes EFI_HII_IMAGE_PROTOCOL.NewImage() implicitly.
 
   @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.
   @param  PackageList            Handle of the package list where this image will
                                  be added.
   @param  ImageId                On return, contains the new image id, which is
@@ -55,26 +54,28 @@ EFI_STATUS
   );
 
 /**
   Return the information about the image, associated with the package list.
   The prototype of this extension function is the same with EFI_HII_IMAGE_PROTOCOL.GetImage().
-  Same with EFI_HII_IMAGE_PROTOCOL.SetImage(),this protocol invokes EFI_HII_IMAGE_PROTOCOL.SetImage() implicitly.
+
+  This function is similar to EFI_HII_IMAGE_PROTOCOL.GetImage().The difference is that
+  this function will locate all EFI_HII_IMAGE_DECODER_PROTOCOL instances installed in the
+  system if the decoder of the certain image type is not supported by the
+  EFI_HII_IMAGE_EX_PROTOCOL. The function will attempt to decode the image to the
+  EFI_IMAGE_INPUT using the first EFI_HII_IMAGE_DECODER_PROTOCOL instance that
+  supports the requested image type.
 
   @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.
-  @param  PackageList            Handle of the package list where this image will
-                                 be searched.
-  @param  ImageId                The image's id,, which is unique within
-                                 PackageList.
+  @param  PackageList            The package list in the HII database to search for the
+                                 specified image.
+  @param  ImageId                The image's id, which is unique within PackageList.
   @param  Image                  Points to the image.
 
   @retval EFI_SUCCESS            The new image was returned successfully.
-  @retval EFI_NOT_FOUND          The image specified by ImageId is not in the
-                                 database. The specified PackageList is not in
-                                 the database.
-  @retval EFI_BUFFER_TOO_SMALL   The buffer specified by ImageSize is too small to
-                                 hold the image.
-  @retval EFI_INVALID_PARAMETER  The Image or ImageSize was NULL.
+  @retval EFI_NOT_FOUND          The image specified by ImageId is not available. The specified
+                                 PackageList is not in the Database.
+  @retval EFI_INVALID_PARAMETER  Image was NULL or ImageId was 0.
   @retval EFI_OUT_OF_RESOURCES   The bitmap could not be retrieved because there
                                  was not enough memory.
 
 **/
 typedef
@@ -85,25 +86,26 @@ EFI_STATUS
   IN        EFI_IMAGE_ID                    ImageId,
   OUT       EFI_IMAGE_INPUT                 *Image
   );
 
 /**
-  Change the information about the image. The prototype of this extension
-  function is the same with EFI_HII_IMAGE_PROTOCOL.SetImage().  Same with
-  EFI_HII_IMAGE_PROTOCOL.DrawImageId(),this protocol invokes EFI_HII_IMAGE_PROTOCOL.DrawImageId() implicitly.
+  Change the information about the image.
+
+  Same with EFI_HII_IMAGE_PROTOCOL.SetImage(),this protocol invokes
+  EFI_HII_IMAGE_PROTOCOL.SetImage()implicitly.
 
   @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.
   @param  PackageList            The package list containing the images.
-  @param  ImageId                The image's id,, which is unique within
-                                 PackageList.
+  @param  ImageId                The image's id, which is unique within PackageList.
   @param  Image                  Points to the image.
 
-  @retval EFI_SUCCESS            The new image was updated successfully.
+  @retval EFI_SUCCESS            The new image was successfully updated.
   @retval EFI_NOT_FOUND          The image specified by ImageId is not in the
                                  database. The specified PackageList is not in
                                  the database.
-  @retval EFI_INVALID_PARAMETER  The Image was NULL.
+  @retval EFI_INVALID_PARAMETER  The Image was NULL, the ImageId was 0 or
+                                 the Image->Bitmap was NULL.
 
 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_HII_SET_IMAGE_EX)(
@@ -112,34 +114,35 @@ EFI_STATUS
   IN        EFI_IMAGE_ID                ImageId,
   IN CONST  EFI_IMAGE_INPUT             *Image
   );
 
 /**
-  Renders an image to a bitmap or to the display. The prototype of this extension
-  function is the same with EFI_HII_IMAGE_PROTOCOL.DrawImage().
-  Same with EFI_HII_IMAGE_PROTOCOL.SetImage(),this protocol invokes EFI_HII_IMAGE_PROTOCOL.SetImage() implicitly.
+  Renders an image to a bitmap or to the display.
+
+  The prototype of this extension function is the same with
+  EFI_HII_IMAGE_PROTOCOL.DrawImage(). This protocol invokes
+  EFI_HII_IMAGE_PROTOCOL.DrawImage() implicitly.
 
   @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.
   @param  Flags                  Describes how the image is to be drawn.
   @param  Image                  Points to the image to be displayed.
   @param  Blt                    If this points to a non-NULL on entry, this points
                                  to the image, which is Width pixels wide and
                                  Height pixels high.  The image will be drawn onto
                                  this image and  EFI_HII_DRAW_FLAG_CLIP is implied.
-                                 If this points to a  NULL on entry, then a buffer
-                                 will be allocated to hold  the generated image and
+                                 If this points to a NULL on entry, then a buffer
+                                 will be allocated to hold the generated image and
                                  the pointer updated on exit. It is the caller's
                                  responsibility to free this buffer.
   @param  BltX                   Specifies the offset from the left and top edge of
-                                 the  output image of the first pixel in the image.
+                                 the output image of the first pixel in the image.
   @param  BltY                   Specifies the offset from the left and top edge of
-                                 the  output image of the first pixel in the image.
+                                 the output image of the first pixel in the image.
 
   @retval EFI_SUCCESS            The image was successfully drawn.
   @retval EFI_OUT_OF_RESOURCES   Unable to allocate an output buffer for Blt.
   @retval EFI_INVALID_PARAMETER  The Image or Blt was NULL.
-                                 Any combination of Flags is invalid.
 
 **/
 typedef
 EFI_STATUS
 (EFIAPI *EFI_HII_DRAW_IMAGE_EX)(
@@ -151,21 +154,24 @@ EFI_STATUS
   IN        UINTN                       BltY
   );
 
 /**
   Renders an image to a bitmap or the screen containing the contents of the specified
-  image. The prototype of this extension function is the same with E
-  FI_HII_IMAGE_PROTOCOL.DrawImageId().
-  Same with EFI_HII_IMAGE_PROTOCOL.DrawImageId(),this protocol invokes
-EFI_HII_IMAGE_PROTOCOL.DrawImageId() implicitly.
+  image.
+
+  This function is similar to EFI_HII_IMAGE_PROTOCOL.DrawImageId(). The difference is that
+  this function will locate all EFI_HII_IMAGE_DECODER_PROTOCOL instances installed in the
+  system if the decoder of the certain image type is not supported by the
+  EFI_HII_IMAGE_EX_PROTOCOL. The function will attempt to decode the image to the
+  EFI_IMAGE_INPUT using the first EFI_HII_IMAGE_DECODER_PROTOCOL instance that
+  supports the requested image type.
 
   @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.
   @param  Flags                  Describes how the image is to be drawn.
   @param  PackageList            The package list in the HII database to search for
                                  the  specified image.
-  @param  ImageId                The image's id, which is unique within
-                                 PackageList.
+  @param  ImageId                The image's id, which is unique within PackageList.
   @param  Blt                    If this points to a non-NULL on entry, this points
                                  to the image, which is Width pixels wide and
                                  Height pixels high. The image will be drawn onto
                                  this image and EFI_HII_DRAW_FLAG_CLIP is implied.
                                  If this points to a NULL on entry, then a buffer
@@ -177,11 +183,11 @@ EFI_HII_IMAGE_PROTOCOL.DrawImageId() implicitly.
   @param  BltY                   Specifies the offset from the left and top edge of
                                  the output image of the first pixel in the image.
 
   @retval EFI_SUCCESS            The image was successfully drawn.
   @retval EFI_OUT_OF_RESOURCES   Unable to allocate an output buffer for Blt.
-  @retval EFI_INVALID_PARAMETER  The Blt was NULL.
+  @retval EFI_INVALID_PARAMETER  The Blt was NULL or ImageId was 0.
   @retval EFI_NOT_FOUND          The image specified by ImageId is not in the database.
                                  The specified PackageList is not in the database.
 
 **/
 typedef
@@ -204,19 +210,19 @@ EFI_STATUS
   system if the decoder of image type is not supported by the EFI_HII_IMAGE_EX_PROTOCOL.
 
   @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.
   @param  PackageList            Handle of the package list where this image will
                                  be searched.
-  @param  ImageId                The image's id,, which is unique within PackageList.
+  @param  ImageId                The image's id, which is unique within PackageList.
   @param  Image                  Points to the image.
 
   @retval EFI_SUCCESS            The new image was returned successfully.
   @retval EFI_NOT_FOUND          The image specified by ImageId is not in the
                                  database. The specified PackageList is not in the database.
   @retval EFI_BUFFER_TOO_SMALL   The buffer specified by ImageSize is too small to
                                  hold the image.
-  @retval EFI_INVALID_PARAMETER  The Image or ImageSize was NULL.
+  @retval EFI_INVALID_PARAMETER  The Image was NULL or the ImageId was 0.
   @retval EFI_OUT_OF_RESOURCES   The bitmap could not be retrieved because there
                                  was not enough memory.
 
 **/
 typedef
-- 
1.9.5.msysgit.1



^ permalink raw reply related	[flat|nested] 9+ messages in thread