Refine the comments to follow spec.

Signed-off-by: Eric Dong <eric.dong@intel.com>
Reviewed-by: Liming Gao <liming.gao@intel.com>
git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@14572 6f19259b-4bc3-4df7-8a09-765794883524

diff --git a/MdePkg/Include/Protocol/HiiConfigRouting.h b/MdePkg/Include/Protocol/HiiConfigRouting.h
index ce38a2559cb2e4a8fb842375ce7da40366ea74ab..4423a5c04d1a414aff6a4cdd60666aff3f00fe19 100644 (file)
--- a/MdePkg/Include/Protocol/HiiConfigRouting.h
+++ b/MdePkg/Include/Protocol/HiiConfigRouting.h
@@ -124,11 +124,11 @@ EFI_STATUS
   \r
   @param This     Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.\r
   \r
   \r
   @param This     Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance.\r
   \r

-  @param Results  A null-terminated string in <MultiConfigAltResp>\r
-                  format which has all values filled in for the\r
-                  names in the Request string.\r
-                  String to be allocated by this function.\r
-                  De-allocation is up to the caller.\r
+  @param  Results Null-terminated Unicode string in\r
+                  <MultiConfigAltResp> format which has all values\r
+                  filled in for the entirety of the current HII \r
+                  database. String to be allocated by the  called \r
+                  function. De-allocation is up to the caller.\r

   \r
   @retval EFI_SUCCESS             The Results string is filled with the\r
                                   values corresponding to all requested\r
   \r
   @retval EFI_SUCCESS             The Results string is filled with the\r
                                   values corresponding to all requested\r


@@ -305,8 +305,10 @@ EFI_STATUS
 \r
   @param BlockSize      The length of the Block in units of UINT8.\r
                         On input, this is the size of the Block. On\r
 \r
   @param BlockSize      The length of the Block in units of UINT8.\r
                         On input, this is the size of the Block. On\r

-                        output, if successful, contains the index of\r
-                        the last modified byte in the Block.\r
+                        output, if successful, contains the largest \r
+                        index of the modified byte in the Block, or\r
+                        the required buffer size if the Block is not\r
+                        large enough.\r

 \r
   @param Progress       On return, points to an element of the\r
                         ConfigResp string filled in with the offset\r
 \r
   @param Progress       On return, points to an element of the\r
                         ConfigResp string filled in with the offset\r


@@ -332,6 +334,9 @@ EFI_STATUS
   @retval EFI_NOT_FOUND          Target for the specified routing data was not found.\r
                                  Progress points to the "G" in "GUID" of the errant\r
                                  routing data.\r
   @retval EFI_NOT_FOUND          Target for the specified routing data was not found.\r
                                  Progress points to the "G" in "GUID" of the errant\r
                                  routing data.\r

+  @retval EFI_BUFFER_TOO_SMALL   Block not large enough. Progress undefined. \r
+                                 BlockSize is updated with the required buffer size.\r
+\r

 **/\r
 typedef\r
 EFI_STATUS\r
 **/\r
 typedef\r
 EFI_STATUS\r

diff --git a/MdePkg/Include/Protocol/HiiDatabase.h b/MdePkg/Include/Protocol/HiiDatabase.h
index 1310dc6e012114ed802c0b0c1ef533c5843380ee..474d84048587806f24763ad62661810f7114046a 100644 (file)
--- a/MdePkg/Include/Protocol/HiiDatabase.h
+++ b/MdePkg/Include/Protocol/HiiDatabase.h
@@ -223,7 +223,9 @@ EFI_STATUS
                                 updated with a value that will\r
                                 enable the data to fit.\r
   @retval EFI_NOT_FOUND         No matching handle could be found in database.\r
                                 updated with a value that will\r
                                 enable the data to fit.\r
   @retval EFI_NOT_FOUND         No matching handle could be found in database.\r

-  @retval EFI_INVALID_PARAMETER Handle or HandleBufferLength was NULL.\r
+  @retval EFI_INVALID_PARAMETER HandleBufferLength was NULL.\r
+  @retval EFI_INVALID_PARAMETER The value referenced by HandleBufferLength was not\r
+                                zero and Handle was NULL.\r

   @retval EFI_INVALID_PARAMETER PackageType is not a EFI_HII_PACKAGE_TYPE_GUID but\r
                                 PackageGuid is not NULL, PackageType is a EFI_HII_\r
                                 PACKAGE_TYPE_GUID but PackageGuid is NULL.\r
   @retval EFI_INVALID_PARAMETER PackageType is not a EFI_HII_PACKAGE_TYPE_GUID but\r
                                 PackageGuid is not NULL, PackageType is a EFI_HII_\r
                                 PACKAGE_TYPE_GUID but PackageGuid is NULL.\r


@@ -271,6 +273,13 @@ EFI_STATUS
   \r
   @retval EFI_OUT_OF_RESOURCES  BufferSize is too small to hold the package.\r
 \r
   \r
   @retval EFI_OUT_OF_RESOURCES  BufferSize is too small to hold the package.\r
 \r

+  @retval EFI_NOT_FOUND         The specifiecd Handle could not be found in the\r
+                                current database.\r
+  \r
+  @retval EFI_INVALID_PARAMETER BufferSize was NULL.\r
+  \r
+  @retval EFI_INVALID_PARAMETER The value referenced by BufferSize was not zero \r
+                                and Buffer was NULL.\r

 **/\r
 typedef\r
 EFI_STATUS\r
 **/\r
 typedef\r
 EFI_STATUS\r


@@ -393,6 +402,11 @@ EFI_STATUS
                                 KeyGuidBufferLength is updated\r
                                 with a value that will enable\r
                                 the data to fit.\r
                                 KeyGuidBufferLength is updated\r
                                 with a value that will enable\r
                                 the data to fit.\r

+  @retval EFI_INVALID_PARAMETER The KeyGuidBufferLength is NULL.\r
+  @retval EFI_INVALID_PARAMETER The value referenced by \r
+                                KeyGuidBufferLength is not\r
+                                zero and KeyGuidBuffer is NULL.\r
+  @retval EFI_NOT_FOUND         There was no keyboard layout.\r

 \r
 **/\r
 typedef\r
 \r
 **/\r
 typedef\r

diff --git a/MdePkg/Include/Protocol/HiiFont.h b/MdePkg/Include/Protocol/HiiFont.h
index 7e9c9c39641d6f3409311a49d89fb9e5c73fe8c9..6314df8e371c266bb6a2105674f8611e110df530 100644 (file)
--- a/MdePkg/Include/Protocol/HiiFont.h
+++ b/MdePkg/Include/Protocol/HiiFont.h
@@ -56,7 +56,7 @@ typedef struct _EFI_HII_ROW_INFO {
   UINTN   LineWidth;  ///< The width of the text on the line, in pixels.\r
   \r
   ///\r
   UINTN   LineWidth;  ///< The width of the text on the line, in pixels.\r
   \r
   ///\r

-  /// The number of pixels above the bottom of the row of the font baseline or 0 if none.  \r
+  /// The font baseline offset in pixels from the bottom of the row, or 0 if none.\r

   ///\r
   UINTN   BaselineOffset;\r
 } EFI_HII_ROW_INFO;\r
   ///\r
   UINTN   BaselineOffset;\r
 } EFI_HII_ROW_INFO;\r


@@ -427,9 +427,12 @@ EFI_STATUS
                         information about. If NULL, then the information \r
                         about the system default font will be returned.\r
 \r
                         information about. If NULL, then the information \r
                         about the system default font will be returned.\r
 \r

-  @param StringInfoOut  Upon return, contains the matching\r
-                        font's information. If NULL, then no\r
-                        information is returned.\r
+  @param  StringInfoOut Upon return, contains the matching font's information.\r
+                        If NULL, then no information is returned. This buffer\r
+                        is allocated with a call to the Boot Service AllocatePool().\r
+                        It is the caller's responsibility to call the Boot \r
+                        Service FreePool() when the caller no longer requires\r
+                        the contents of StringInfoOut.\r

 \r
   @param String         Points to the string which will be tested to\r
                         determine if all characters are available. If\r
 \r
   @param String         Points to the string which will be tested to\r
                         determine if all characters are available. If\r

diff --git a/MdePkg/Include/Protocol/HiiString.h b/MdePkg/Include/Protocol/HiiString.h
index 496ffa659e76b0af54d1a43cf89e2d1bb563386e..6400b51d388c76089dfa6676a87682a723370f7a 100644 (file)
--- a/MdePkg/Include/Protocol/HiiString.h
+++ b/MdePkg/Include/Protocol/HiiString.h
@@ -88,14 +88,16 @@ EFI_STATUS
 \r
   @retval EFI_SUCCESS            The string was returned successfully.\r
   @retval EFI_NOT_FOUND          The string specified by StringId is not available.\r
 \r
   @retval EFI_SUCCESS            The string was returned successfully.\r
   @retval EFI_NOT_FOUND          The string specified by StringId is not available.\r

-  @retval EFI_NOT_FOUND          The string specified by StringId is available but\r
-                                 not in the specified language.\r

                                  The specified PackageList is not in the database.\r
                                  The specified PackageList is not in the database.\r

+  @retval EFI_INVALID_LANGUAGE    The string specified by StringId is available but \r
+                                  not in the specified language.\r

   @retval EFI_BUFFER_TOO_SMALL   The buffer specified by StringSize is too small to\r
                                  hold the string.\r
   @retval EFI_BUFFER_TOO_SMALL   The buffer specified by StringSize is too small to\r
                                  hold the string.\r

-  @retval EFI_INVALID_PARAMETER  The String or Language or StringSize was NULL.\r
-  @retval EFI_OUT_OF_RESOURCES   There were insufficient resources to complete the\r
-                                 request.\r
+  @retval EFI_INVALID_PARAMETER   The Language or StringSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER   The value referenced by StringSize was not zero and\r
+                                  String was NULL.\r
+  @retval EFI_OUT_OF_RESOURCES    There were insufficient resources to complete the\r
+                                  request.\r

 \r
 **/\r
 typedef\r
 \r
 **/\r
 typedef\r


@@ -157,7 +159,9 @@ EFI_STATUS
                                  the length of Languages, in bytes.\r
 \r
   @retval EFI_SUCCESS            The languages were returned successfully.\r
                                  the length of Languages, in bytes.\r
 \r
   @retval EFI_SUCCESS            The languages were returned successfully.\r

-  @retval EFI_INVALID_PARAMETER  The Languages or LanguagesSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER  The LanguagesSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER  The value referenced by LanguagesSize is not zero\r
+                                 and Languages is NULL.\r

   @retval EFI_BUFFER_TOO_SMALL   The LanguagesSize is too small to hold the list of\r
                                  supported languages. LanguageSize is updated to\r
                                  contain the required size.\r
   @retval EFI_BUFFER_TOO_SMALL   The LanguagesSize is too small to hold the list of\r
                                  supported languages. LanguageSize is updated to\r
                                  contain the required size.\r


@@ -196,15 +200,16 @@ EFI_STATUS
                                  points to the length of SecondaryLanguages in bytes.\r
 \r
   @retval EFI_SUCCESS            Secondary languages were correctly returned.\r
                                  points to the length of SecondaryLanguages in bytes.\r
 \r
   @retval EFI_SUCCESS            Secondary languages were correctly returned.\r

-  @retval EFI_INVALID_PARAMETER  PrimaryLanguage or SecondaryLanguages or\r
-                                 SecondaryLanguagesSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER  PrimaryLanguage or SecondaryLanguagesSize was NULL.\r
+  @retval EFI_INVALID_PARAMETER  The value referenced by SecondaryLanguagesSize is not\r
+                                 zero and SecondaryLanguages is NULL.\r

   @retval EFI_BUFFER_TOO_SMALL   The buffer specified by SecondaryLanguagesSize is\r
                                  too small to hold the returned information.\r
                                  SecondaryLanguageSize is updated to hold the size of\r
                                  the buffer required.\r
   @retval EFI_INVALID_LANGUAGE   The language specified by PrimaryLanguage is not\r
                                  present in the specified package list.\r
   @retval EFI_BUFFER_TOO_SMALL   The buffer specified by SecondaryLanguagesSize is\r
                                  too small to hold the returned information.\r
                                  SecondaryLanguageSize is updated to hold the size of\r
                                  the buffer required.\r
   @retval EFI_INVALID_LANGUAGE   The language specified by PrimaryLanguage is not\r
                                  present in the specified package list.\r

-  @retval EFI_NOT_FOUND          The specified PackageList is not in the Database.                                \r
+  @retval EFI_NOT_FOUND          The specified PackageList is not in the Database.\r

 \r
 **/\r
 typedef\r
 \r
 **/\r
 typedef\r