From 5795218e88685dea1991469ebabfe2887a3679bb Mon Sep 17 00:00:00 2001 From: Eric Dong Date: Tue, 20 Aug 2013 07:08:25 +0000 Subject: [PATCH] Refine the comments to follow spec. Signed-off-by: Eric Dong Reviewed-by: Liming Gao git-svn-id: https://svn.code.sf.net/p/edk2/code/trunk/edk2@14572 6f19259b-4bc3-4df7-8a09-765794883524 --- MdePkg/Include/Protocol/HiiConfigRouting.h | 19 +++++++++++------- MdePkg/Include/Protocol/HiiDatabase.h | 16 ++++++++++++++- MdePkg/Include/Protocol/HiiFont.h | 11 +++++++---- MdePkg/Include/Protocol/HiiString.h | 23 +++++++++++++--------- 4 files changed, 48 insertions(+), 21 deletions(-) diff --git a/MdePkg/Include/Protocol/HiiConfigRouting.h b/MdePkg/Include/Protocol/HiiConfigRouting.h index ce38a2559c..4423a5c04d 100644 --- a/MdePkg/Include/Protocol/HiiConfigRouting.h +++ b/MdePkg/Include/Protocol/HiiConfigRouting.h @@ -124,11 +124,11 @@ EFI_STATUS @param This Points to the EFI_HII_CONFIG_ROUTING_PROTOCOL instance. - @param Results A null-terminated string in - format which has all values filled in for the - names in the Request string. - String to be allocated by this function. - De-allocation is up to the caller. + @param Results Null-terminated Unicode string in + format which has all values + filled in for the entirety of the current HII + database. String to be allocated by the called + function. De-allocation is up to the caller. @retval EFI_SUCCESS The Results string is filled with the values corresponding to all requested @@ -305,8 +305,10 @@ EFI_STATUS @param BlockSize The length of the Block in units of UINT8. On input, this is the size of the Block. On - output, if successful, contains the index of - the last modified byte in the Block. + output, if successful, contains the largest + index of the modified byte in the Block, or + the required buffer size if the Block is not + large enough. @param Progress On return, points to an element of the ConfigResp string filled in with the offset @@ -332,6 +334,9 @@ EFI_STATUS @retval EFI_NOT_FOUND Target for the specified routing data was not found. Progress points to the "G" in "GUID" of the errant routing data. + @retval EFI_BUFFER_TOO_SMALL Block not large enough. Progress undefined. + BlockSize is updated with the required buffer size. + **/ typedef EFI_STATUS diff --git a/MdePkg/Include/Protocol/HiiDatabase.h b/MdePkg/Include/Protocol/HiiDatabase.h index 1310dc6e01..474d840485 100644 --- a/MdePkg/Include/Protocol/HiiDatabase.h +++ b/MdePkg/Include/Protocol/HiiDatabase.h @@ -223,7 +223,9 @@ EFI_STATUS updated with a value that will enable the data to fit. @retval EFI_NOT_FOUND No matching handle could be found in database. - @retval EFI_INVALID_PARAMETER Handle or HandleBufferLength was NULL. + @retval EFI_INVALID_PARAMETER HandleBufferLength was NULL. + @retval EFI_INVALID_PARAMETER The value referenced by HandleBufferLength was not + zero and Handle was NULL. @retval EFI_INVALID_PARAMETER PackageType is not a EFI_HII_PACKAGE_TYPE_GUID but PackageGuid is not NULL, PackageType is a EFI_HII_ PACKAGE_TYPE_GUID but PackageGuid is NULL. @@ -271,6 +273,13 @@ EFI_STATUS @retval EFI_OUT_OF_RESOURCES BufferSize is too small to hold the package. + @retval EFI_NOT_FOUND The specifiecd Handle could not be found in the + current database. + + @retval EFI_INVALID_PARAMETER BufferSize was NULL. + + @retval EFI_INVALID_PARAMETER The value referenced by BufferSize was not zero + and Buffer was NULL. **/ typedef EFI_STATUS @@ -393,6 +402,11 @@ EFI_STATUS KeyGuidBufferLength is updated with a value that will enable the data to fit. + @retval EFI_INVALID_PARAMETER The KeyGuidBufferLength is NULL. + @retval EFI_INVALID_PARAMETER The value referenced by + KeyGuidBufferLength is not + zero and KeyGuidBuffer is NULL. + @retval EFI_NOT_FOUND There was no keyboard layout. **/ typedef diff --git a/MdePkg/Include/Protocol/HiiFont.h b/MdePkg/Include/Protocol/HiiFont.h index 7e9c9c3964..6314df8e37 100644 --- 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. /// - /// The number of pixels above the bottom of the row of the font baseline or 0 if none. + /// The font baseline offset in pixels from the bottom of the row, or 0 if none. /// UINTN BaselineOffset; } EFI_HII_ROW_INFO; @@ -427,9 +427,12 @@ EFI_STATUS information about. If NULL, then the information about the system default font will be returned. - @param StringInfoOut Upon return, contains the matching - font's information. If NULL, then no - information is returned. + @param StringInfoOut Upon return, contains the matching font's information. + If NULL, then no information is returned. This buffer + is allocated with a call to the Boot Service AllocatePool(). + It is the caller's responsibility to call the Boot + Service FreePool() when the caller no longer requires + the contents of StringInfoOut. @param String Points to the string which will be tested to determine if all characters are available. If diff --git a/MdePkg/Include/Protocol/HiiString.h b/MdePkg/Include/Protocol/HiiString.h index 496ffa659e..6400b51d38 100644 --- a/MdePkg/Include/Protocol/HiiString.h +++ b/MdePkg/Include/Protocol/HiiString.h @@ -88,14 +88,16 @@ EFI_STATUS @retval EFI_SUCCESS The string was returned successfully. @retval EFI_NOT_FOUND The string specified by StringId is not available. - @retval EFI_NOT_FOUND The string specified by StringId is available but - not in the specified language. The specified PackageList is not in the database. + @retval EFI_INVALID_LANGUAGE The string specified by StringId is available but + not in the specified language. @retval EFI_BUFFER_TOO_SMALL The buffer specified by StringSize is too small to hold the string. - @retval EFI_INVALID_PARAMETER The String or Language or StringSize was NULL. - @retval EFI_OUT_OF_RESOURCES There were insufficient resources to complete the - request. + @retval EFI_INVALID_PARAMETER The Language or StringSize was NULL. + @retval EFI_INVALID_PARAMETER The value referenced by StringSize was not zero and + String was NULL. + @retval EFI_OUT_OF_RESOURCES There were insufficient resources to complete the + request. **/ typedef @@ -157,7 +159,9 @@ EFI_STATUS the length of Languages, in bytes. @retval EFI_SUCCESS The languages were returned successfully. - @retval EFI_INVALID_PARAMETER The Languages or LanguagesSize was NULL. + @retval EFI_INVALID_PARAMETER The LanguagesSize was NULL. + @retval EFI_INVALID_PARAMETER The value referenced by LanguagesSize is not zero + and Languages is NULL. @retval EFI_BUFFER_TOO_SMALL The LanguagesSize is too small to hold the list of supported languages. LanguageSize is updated to contain the required size. @@ -196,15 +200,16 @@ EFI_STATUS points to the length of SecondaryLanguages in bytes. @retval EFI_SUCCESS Secondary languages were correctly returned. - @retval EFI_INVALID_PARAMETER PrimaryLanguage or SecondaryLanguages or - SecondaryLanguagesSize was NULL. + @retval EFI_INVALID_PARAMETER PrimaryLanguage or SecondaryLanguagesSize was NULL. + @retval EFI_INVALID_PARAMETER The value referenced by SecondaryLanguagesSize is not + zero and SecondaryLanguages is NULL. @retval EFI_BUFFER_TOO_SMALL The buffer specified by SecondaryLanguagesSize is too small to hold the returned information. SecondaryLanguageSize is updated to hold the size of the buffer required. @retval EFI_INVALID_LANGUAGE The language specified by PrimaryLanguage is not present in the specified package list. - @retval EFI_NOT_FOUND The specified PackageList is not in the Database. + @retval EFI_NOT_FOUND The specified PackageList is not in the Database. **/ typedef -- 2.39.2