MdePkg/HiiImageEx: Fix incorrect comments of functions

https://bugzilla.tianocore.org/show_bug.cgi?id=383

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>
Reviewed-by: Ruiyu Ni <ruiyu.ni@intel.com>
Reviewed-by: Liming Gao <liming.gao@intel.com>

diff --git a/MdePkg/Include/Protocol/HiiImageEx.h b/MdePkg/Include/Protocol/HiiImageEx.h
index b92fc3a0cd168dbc140ecf769a4ddd1c51388656..5a48380e46126508b5dbefc294d6d99ddd298929 100644 (file)
--- a/MdePkg/Include/Protocol/HiiImageEx.h
+++ b/MdePkg/Include/Protocol/HiiImageEx.h
@@ -28,8 +28,7 @@ typedef struct _EFI_HII_IMAGE_EX_PROTOCOL EFI_HII_IMAGE_EX_PROTOCOL;
 \r
 /**\r
   The prototype of this extension function is the same with EFI_HII_IMAGE_PROTOCOL.NewImage().\r
-  Same with EFI_HII_IMAGE_PROTOCOL.NewImage().This protocol invokes\r
-EFI_HII_IMAGE_PROTOCOL.NewImage() implicitly.\r
+  This protocol invokes EFI_HII_IMAGE_PROTOCOL.NewImage() implicitly.\r
 \r
   @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.\r
   @param  PackageList            Handle of the package list where this image will\r
@@ -57,22 +56,24 @@ EFI_STATUS
 /**\r
   Return the information about the image, associated with the package list.\r
   The prototype of this extension function is the same with EFI_HII_IMAGE_PROTOCOL.GetImage().\r
-  Same with EFI_HII_IMAGE_PROTOCOL.SetImage(),this protocol invokes EFI_HII_IMAGE_PROTOCOL.SetImage() implicitly.\r
+\r
+  This function is similar to EFI_HII_IMAGE_PROTOCOL.GetImage().The difference is that\r
+  this function will locate all EFI_HII_IMAGE_DECODER_PROTOCOL instances installed in the\r
+  system if the decoder of the certain image type is not supported by the\r
+  EFI_HII_IMAGE_EX_PROTOCOL. The function will attempt to decode the image to the\r
+  EFI_IMAGE_INPUT using the first EFI_HII_IMAGE_DECODER_PROTOCOL instance that\r
+  supports the requested image type.\r
 \r
   @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.\r
-  @param  PackageList            Handle of the package list where this image will\r
-                                 be searched.\r
-  @param  ImageId                The image's id,, which is unique within\r
-                                 PackageList.\r
+  @param  PackageList            The package list in the HII database to search for the\r
+                                 specified image.\r
+  @param  ImageId                The image's id, which is unique within PackageList.\r
   @param  Image                  Points to the image.\r
 \r
   @retval EFI_SUCCESS            The new image was returned successfully.\r
-  @retval EFI_NOT_FOUND          The image specified by ImageId is not in the\r
-                                 database. The specified PackageList is not in\r
-                                 the database.\r
-  @retval EFI_BUFFER_TOO_SMALL   The buffer specified by ImageSize is too small to\r
-                                 hold the image.\r
-  @retval EFI_INVALID_PARAMETER  The Image or ImageSize was NULL.\r
+  @retval EFI_NOT_FOUND          The image specified by ImageId is not available. The specified\r
+                                 PackageList is not in the Database.\r
+  @retval EFI_INVALID_PARAMETER  Image was NULL or ImageId was 0.\r
   @retval EFI_OUT_OF_RESOURCES   The bitmap could not be retrieved because there\r
                                  was not enough memory.\r
 \r
@@ -87,21 +88,22 @@ EFI_STATUS
   );\r
 \r
 /**\r
-  Change the information about the image. The prototype of this extension\r
-  function is the same with EFI_HII_IMAGE_PROTOCOL.SetImage().  Same with\r
-  EFI_HII_IMAGE_PROTOCOL.DrawImageId(),this protocol invokes EFI_HII_IMAGE_PROTOCOL.DrawImageId() implicitly.\r
+  Change the information about the image.\r
+\r
+  Same with EFI_HII_IMAGE_PROTOCOL.SetImage(),this protocol invokes\r
+  EFI_HII_IMAGE_PROTOCOL.SetImage()implicitly.\r
 \r
   @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.\r
   @param  PackageList            The package list containing the images.\r
-  @param  ImageId                The image's id,, which is unique within\r
-                                 PackageList.\r
+  @param  ImageId                The image's id, which is unique within PackageList.\r
   @param  Image                  Points to the image.\r
 \r
-  @retval EFI_SUCCESS            The new image was updated successfully.\r
+  @retval EFI_SUCCESS            The new image was successfully updated.\r
   @retval EFI_NOT_FOUND          The image specified by ImageId is not in the\r
                                  database. The specified PackageList is not in\r
                                  the database.\r
-  @retval EFI_INVALID_PARAMETER  The Image was NULL.\r
+  @retval EFI_INVALID_PARAMETER  The Image was NULL, the ImageId was 0 or\r
+                                 the Image->Bitmap was NULL.\r
 \r
 **/\r
 typedef\r
@@ -114,9 +116,11 @@ EFI_STATUS
   );\r
 \r
 /**\r
-  Renders an image to a bitmap or to the display. The prototype of this extension\r
-  function is the same with EFI_HII_IMAGE_PROTOCOL.DrawImage().\r
-  Same with EFI_HII_IMAGE_PROTOCOL.SetImage(),this protocol invokes EFI_HII_IMAGE_PROTOCOL.SetImage() implicitly.\r
+  Renders an image to a bitmap or to the display.\r
+\r
+  The prototype of this extension function is the same with\r
+  EFI_HII_IMAGE_PROTOCOL.DrawImage(). This protocol invokes\r
+  EFI_HII_IMAGE_PROTOCOL.DrawImage() implicitly.\r
 \r
   @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.\r
   @param  Flags                  Describes how the image is to be drawn.\r
@@ -125,19 +129,18 @@ EFI_STATUS
                                  to the image, which is Width pixels wide and\r
                                  Height pixels high.  The image will be drawn onto\r
                                  this image and  EFI_HII_DRAW_FLAG_CLIP is implied.\r
-                                 If this points to a  NULL on entry, then a buffer\r
-                                 will be allocated to hold  the generated image and\r
+                                 If this points to a NULL on entry, then a buffer\r
+                                 will be allocated to hold the generated image and\r
                                  the pointer updated on exit. It is the caller's\r
                                  responsibility to free this buffer.\r
   @param  BltX                   Specifies the offset from the left and top edge of\r
-                                 the  output image of the first pixel in the image.\r
+                                 the output image of the first pixel in the image.\r
   @param  BltY                   Specifies the offset from the left and top edge of\r
-                                 the  output image of the first pixel in the image.\r
+                                 the output image of the first pixel in the image.\r
 \r
   @retval EFI_SUCCESS            The image was successfully drawn.\r
   @retval EFI_OUT_OF_RESOURCES   Unable to allocate an output buffer for Blt.\r
   @retval EFI_INVALID_PARAMETER  The Image or Blt was NULL.\r
-                                 Any combination of Flags is invalid.\r
 \r
 **/\r
 typedef\r
@@ -153,17 +156,20 @@ EFI_STATUS
 \r
 /**\r
   Renders an image to a bitmap or the screen containing the contents of the specified\r
-  image. The prototype of this extension function is the same with E\r
-  FI_HII_IMAGE_PROTOCOL.DrawImageId().\r
-  Same with EFI_HII_IMAGE_PROTOCOL.DrawImageId(),this protocol invokes\r
-EFI_HII_IMAGE_PROTOCOL.DrawImageId() implicitly.\r
+  image.\r
+\r
+  This function is similar to EFI_HII_IMAGE_PROTOCOL.DrawImageId(). The difference is that\r
+  this function will locate all EFI_HII_IMAGE_DECODER_PROTOCOL instances installed in the\r
+  system if the decoder of the certain image type is not supported by the\r
+  EFI_HII_IMAGE_EX_PROTOCOL. The function will attempt to decode the image to the\r
+  EFI_IMAGE_INPUT using the first EFI_HII_IMAGE_DECODER_PROTOCOL instance that\r
+  supports the requested image type.\r
 \r
   @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.\r
   @param  Flags                  Describes how the image is to be drawn.\r
   @param  PackageList            The package list in the HII database to search for\r
                                  the  specified image.\r
-  @param  ImageId                The image's id, which is unique within\r
-                                 PackageList.\r
+  @param  ImageId                The image's id, which is unique within PackageList.\r
   @param  Blt                    If this points to a non-NULL on entry, this points\r
                                  to the image, which is Width pixels wide and\r
                                  Height pixels high. The image will be drawn onto\r
@@ -179,7 +185,7 @@ EFI_HII_IMAGE_PROTOCOL.DrawImageId() implicitly.
 \r
   @retval EFI_SUCCESS            The image was successfully drawn.\r
   @retval EFI_OUT_OF_RESOURCES   Unable to allocate an output buffer for Blt.\r
-  @retval EFI_INVALID_PARAMETER  The Blt was NULL.\r
+  @retval EFI_INVALID_PARAMETER  The Blt was NULL or ImageId was 0.\r
   @retval EFI_NOT_FOUND          The image specified by ImageId is not in the database.\r
                                  The specified PackageList is not in the database.\r
 \r
@@ -206,7 +212,7 @@ EFI_STATUS
   @param  This                   A pointer to the EFI_HII_IMAGE_EX_PROTOCOL instance.\r
   @param  PackageList            Handle of the package list where this image will\r
                                  be searched.\r
-  @param  ImageId                The image's id,, which is unique within PackageList.\r
+  @param  ImageId                The image's id, which is unique within PackageList.\r
   @param  Image                  Points to the image.\r
 \r
   @retval EFI_SUCCESS            The new image was returned successfully.\r
@@ -214,7 +220,7 @@ EFI_STATUS
                                  database. The specified PackageList is not in the database.\r
   @retval EFI_BUFFER_TOO_SMALL   The buffer specified by ImageSize is too small to\r
                                  hold the image.\r
-  @retval EFI_INVALID_PARAMETER  The Image or ImageSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER  The Image was NULL or the ImageId was 0.\r
   @retval EFI_OUT_OF_RESOURCES   The bitmap could not be retrieved because there\r
                                  was not enough memory.\r
 \r