Clean up ExtendedHiiLib, HiiLib, IfrSupportLib, ExtendedIfrSupportLib for Doxygen comments requirement.

git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@5458 6f19259b-4bc3-4df7-8a09-765794883524

4 files changed, 291 insertions, 5 deletions

diff --git a/MdePkg/Library/HiiLib/HiiLanguage.c b/MdePkg/Library/HiiLib/HiiLanguage.c
index cd2b66063b..f5c8f032a9 100644
--- a/MdePkg/Library/HiiLib/HiiLanguage.c
+++ b/MdePkg/Library/HiiLib/HiiLanguage.c
@@ -15,6 +15,21 @@
 

 #include "InternalHiiLib.h"

 

+/**

+  Determine what is the current language setting. The space reserved for Lang

+  must be at least RFC_3066_ENTRY_SIZE bytes;

+

+  If Lang is NULL, then ASSERT.

+

+  @param  Lang                   Pointer of system language. Lang will always be filled with 

+                                         a valid RFC 3066 language string. If "PlatformLang" is not

+                                         set in the system, the default language specifed by PcdUefiVariableDefaultPlatformLang

+                                         is returned.

+

+  @return  EFI_SUCCESS     If the EFI Variable with "PlatformLang" is set and return in Lang.

+  @return  EFI_NOT_FOUND If the EFI Variable with "PlatformLang" is not set, but a valid default language is return in Lang.

+

+**/

 EFI_STATUS

 EFIAPI

 HiiLibGetCurrentLanguage (

@@ -46,6 +61,18 @@ HiiLibGetCurrentLanguage (
 }

 

 

+/**

+  Get next language from language code list (with separator ';').

+

+  If LangCode is NULL, then ASSERT.

+  If Lang is NULL, then ASSERT.

+

+  @param  LangCode    On input: point to first language in the list. On

+                                 output: point to next language in the list, or

+                                 NULL if no more language in the list.

+  @param  Lang           The first language in the list.

+

+**/

 VOID

 EFIAPI

 HiiLibGetNextLanguage (

@@ -75,6 +102,18 @@ HiiLibGetNextLanguage (
 }

 

 

+/**

+  This function returns the list of supported languages, in the format specified

+  in UEFI specification Appendix M.

+

+  If HiiHandle is not a valid Handle in the default HII database, then ASSERT.

+

+  @param  HiiHandle              The HII package list handle.

+

+  @retval   !NULL  The supported languages.

+  @retval   NULL    If Supported Languages can not be retrived.

+

+**/

 CHAR8 *

 EFIAPI

 HiiLibGetSupportedLanguages (

@@ -118,6 +157,17 @@ HiiLibGetSupportedLanguages (
 }

 

 

+/**

+  This function returns the number of supported languages on HiiHandle.

+

+  If HiiHandle is not a valid Handle in the default HII database, then ASSERT.

+  If not enough resource to complete the operation, then ASSERT.

+

+  @param  HiiHandle              The HII package list handle.

+

+  @return The  number of supported languages.

+

+**/

 UINT16

 EFIAPI

 HiiLibGetSupportedLanguageNumber (

@@ -145,6 +195,19 @@ HiiLibGetSupportedLanguageNumber (
   return LangNumber;

 }

 

+/**

+  This function returns the list of supported 2nd languages, in the format specified

+  in UEFI specification Appendix M.

+

+  If HiiHandle is not a valid Handle in the default HII database, then ASSERT.

+  If not enough resource to complete the operation, then ASSERT.

+

+  @param  HiiHandle              The HII package list handle.

+  @param  FirstLanguage          Pointer to language name buffer.

+  

+  @return The supported languages.

+

+**/

 CHAR8 *

 EFIAPI

 HiiLibGetSupportedSecondaryLanguages (

diff --git a/MdePkg/Library/HiiLib/HiiLib.c b/MdePkg/Library/HiiLib/HiiLib.c
index b0c28e2a80..749b004d9f 100644
--- a/MdePkg/Library/HiiLib/HiiLib.c
+++ b/MdePkg/Library/HiiLib/HiiLib.c
@@ -23,10 +23,6 @@ BOOLEAN mHiiProtocolsInitialized = FALSE;
 

   This function locate Hii relative protocols for later usage.

 

-  @param VOID

-

-  @retval  VOID

-

 **/

 VOID

 LocateHiiProtocols (

@@ -50,10 +46,28 @@ LocateHiiProtocols (
 

 

 

+/**

+  This funciton build the package list based on the package number,

+  the GUID of the package list and the list of pointer which point to

+  package header that defined by UEFI VFR compiler and StringGather

+  tool.

+

+  If there is not enough resource for the new package list,

+  the function will ASSERT.

+

+  @param NumberOfPackages The number of packages be 

+  @param GuidId          The GUID for the package list to be generated.

+  @param Marker          The variable argument list. Each entry represent a specific package header that is

+                         generated by VFR compiler and StrGather tool. The first 4 bytes is a UINT32 value

+                         that indicate the overall length of the package.

+

+  @return The pointer to the package list header.

+

+**/

 EFI_HII_PACKAGE_LIST_HEADER *

 InternalHiiLibPreparePackages (

   IN UINTN           NumberOfPackages,

-  IN CONST EFI_GUID  *GuidId, OPTIONAL

+  IN CONST EFI_GUID  *GuidId,

   VA_LIST            Marker

   )

 {

@@ -106,6 +120,20 @@ InternalHiiLibPreparePackages (
   return PackageListHeader;

 }

 

+/**

+  Assemble EFI_HII_PACKAGE_LIST according to the passed in packages.

+

+  If GuidId is NULL, then ASSERT.

+  If not enough resource to complete the operation, then ASSERT.

+

+  @param  NumberOfPackages       Number of packages.

+  @param  GuidId                          Package GUID.

+  @param  ...                                Variable argument list for packages to be assembled.

+

+  @return EFI_HII_PACKAGE_LIST_HEADER Pointer of EFI_HII_PACKAGE_LIST_HEADER. The function will ASSERT if system has

+                                                                not enough resource to complete the operation.

+

+**/

 EFI_HII_PACKAGE_LIST_HEADER *

 EFIAPI

 HiiLibPreparePackageList (

@@ -127,6 +155,30 @@ HiiLibPreparePackageList (
 }

 

 

+/**

+  This function allocates pool for an EFI_HII_PACKAGE_LIST structure

+  with additional space that is big enough to host all packages described by the variable 

+  argument list of package pointers.  The allocated structure is initialized using NumberOfPackages, 

+  GuidId,  and the variable length argument list of package pointers.

+

+  Then, EFI_HII_PACKAGE_LIST will be register to the default System HII Database. The

+  Handle to the newly registered Package List is returned throught HiiHandle.

+

+  If HiiHandle is NULL, then ASSERT.

+

+  @param  NumberOfPackages    The number of HII packages to register.

+  @param  GuidId              Package List GUID ID.

+  @param  DriverHandle        Optional. If not NULL, the DriverHandle on which an instance of DEVICE_PATH_PROTOCOL is installed.

+                              This DriverHandle uniquely defines the device that the added packages are associated with.

+  @param  HiiHandle           On output, the HiiHandle is update with the handle which can be used to retrieve the Package 

+                              List later. If the functions failed to add the package to the default HII database, this value will

+                              be set to NULL.

+  @param  ...                 The variable argument list describing all HII Package.

+

+  @return  EFI_SUCCESS         If the packages are successfully added to the default HII database.

+  @return  EFI_OUT_OF_RESOURCE Not enough resource to complete the operation.

+

+**/

 EFI_STATUS

 EFIAPI

 HiiLibAddPackages (

@@ -161,6 +213,18 @@ HiiLibAddPackages (
   return Status;

 }

 

+/**

+  Removes a package list from the default HII database.

+

+  If HiiHandle is NULL, then ASSERT.

+  If HiiHandle is not a valid EFI_HII_HANDLE in the default HII database, then ASSERT.

+

+  @param  HiiHandle                The handle that was previously registered to the data base that is requested for removal.

+                                             List later.

+

+  @return  VOID

+

+**/

 VOID

 EFIAPI

 HiiLibRemovePackages (

@@ -177,6 +241,21 @@ HiiLibRemovePackages (
 }

 

 

+/**

+  Determines the handles that are currently active in the database.

+  It's the caller's responsibility to free handle buffer.

+

+  If HandleBufferLength is NULL, then ASSERT.

+  If HiiHandleBuffer is NULL, then ASSERT.

+

+  @param  HandleBufferLength     On input, a pointer to the length of the handle

+                                 buffer. On output, the length of the handle buffer

+                                 that is required for the handles found.

+  @param  HiiHandleBuffer        Pointer to an array of Hii Handles returned.

+

+  @retval EFI_SUCCESS            Get an array of Hii Handles successfully.

+

+**/

 EFI_STATUS

 EFIAPI

 HiiLibGetHiiHandles (

@@ -225,6 +304,18 @@ HiiLibGetHiiHandles (
   return Status;

 }

 

+/**

+  Extract Hii package list GUID for given HII handle.

+

+  If HiiHandle could not be found in the default HII database, then ASSERT.

+  If Guid is NULL, then ASSERT.

+

+  @param  Handle              Hii handle

+  @param  Guid                Package list GUID

+

+  @retval EFI_SUCCESS            Successfully extract GUID from Hii database.

+

+**/

 EFI_STATUS

 EFIAPI

 HiiLibExtractGuidFromHiiHandle (

@@ -269,6 +360,19 @@ HiiLibExtractGuidFromHiiHandle (
   return EFI_SUCCESS;

 }

 

+/**

+  Find HII Handle in the default HII database associated with given Device Path.

+

+  If DevicePath is NULL, then ASSERT.

+

+  @param  DevicePath             Device Path associated with the HII package list

+                                 handle.

+

+  @retval Handle                 HII package list Handle associated with the Device

+                                        Path.

+  @retval NULL                   Hii Package list handle is not found.

+

+**/

 EFI_HII_HANDLE

 EFIAPI

 HiiLibDevicePathToHiiHandle (

@@ -382,6 +486,15 @@ HiiLibDevicePathToHiiHandle (
   return HiiHandle;

 }

 

+/**

+  This function check if the Hii Handle is a valid handle registered

+  in the HII database.

+

+  @param HiiHandle The HII Handle.

+

+  @retval TRUE If it is a valid HII handle.

+  @retval FALSE If it is a invalid HII handle.

+**/

 BOOLEAN

 IsHiiHandleRegistered (

   EFI_HII_HANDLE    HiiHandle

diff --git a/MdePkg/Library/HiiLib/HiiString.c b/MdePkg/Library/HiiLib/HiiString.c
index 7be7f168fa..05e9aa8b68 100644
--- a/MdePkg/Library/HiiLib/HiiString.c
+++ b/MdePkg/Library/HiiLib/HiiString.c
@@ -14,6 +14,25 @@
 

 

 #include "InternalHiiLib.h"

+

+/**

+  This function adds the string into String Package of each language

+  supported by the package list.

+

+  If String is NULL, then ASSERT.

+  If StringId is NULL, the ASSERT.

+  If PackageList could not be found in the default HII database, then ASSERT.

+

+  @param  PackageList            Handle of the package list where this string will

+                                            be added.

+  @param  StringId               On return, contains the new strings id, which is

+                                          unique within PackageList.

+  @param  String                 Points to the new null-terminated string.

+

+  @retval EFI_SUCCESS             The new string was added successfully.

+  @retval EFI_OUT_OF_RESOURCES   Could not add the string due to lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 HiiLibNewString (

@@ -58,6 +77,24 @@ HiiLibNewString (
   

 }

 

+

+/**

+  This function update the specified string in String Package of each language

+  supported by the package list.

+

+  If String is NULL, then ASSERT.

+  If PackageList could not be found in the default HII database, then ASSERT.

+  If StringId is not found in PackageList, then ASSERT.

+

+  @param  PackageList            Handle of the package list where this string will

+                                            be added.

+  @param  StringId               Ths String Id to be updated.

+  @param  String                 Points to the new null-terminated string.

+

+  @retval EFI_SUCCESS            The new string was added successfully.

+  @retval EFI_OUT_OF_RESOURCES   Could not add the string due to lack of resources.

+

+**/

 EFI_STATUS

 EFIAPI

 HiiLibSetString (

@@ -101,6 +138,22 @@ HiiLibSetString (
 }

 

 

+/**

+  Get the string given the StringId and String package Producer's Guid. The caller

+  is responsible to free the *String.

+

+  If PackageList with the matching ProducerGuid is not found, then ASSERT.

+  If PackageList with the matching ProducerGuid is found but no String is

+  specified by StringId is found, then ASSERT.

+

+  @param  ProducerGuid           The Guid of String package list.

+  @param  StringId               The String ID.

+  @param  String                 The output string.

+

+  @retval EFI_SUCCESS            Operation is successful.

+  @retval EFI_OUT_OF_RESOURCES   There is not enought memory in the system.

+

+**/

 EFI_STATUS

 EFIAPI

 HiiLibGetStringFromToken (

@@ -147,6 +200,31 @@ Out:
   return Status;

 }

 

+/**

+  This function try to retrieve string from String package of current language.

+  If fails, it try to retrieve string from String package of first language it support.

+

+  If String is NULL, then ASSERT.

+  If StringSize is NULL, then ASSERT.

+  If PackageList could not be found in the default HII database, then ASSERT.

+  If StringId is not found in PackageList, then ASSERT.

+

+  @param  PackageList     The package list in the HII database to search for

+                                     the specified string.

+  @param  StringId          The string's id, which is unique within

+                                      PackageList.

+  @param  String             Points to the new null-terminated string.

+  @param  StringSize       On entry, points to the size of the buffer pointed

+                                 to by String, in bytes. On return, points to the

+                                 length of the string, in bytes.

+

+  @retval EFI_SUCCESS            The string was returned successfully.

+  @retval EFI_NOT_FOUND          The string specified by StringId is not available.

+  @retval EFI_BUFFER_TOO_SMALL   The buffer specified by StringLength is too small

+                                 to hold the string.

+  @retval EFI_INVALID_PARAMETER  The String or StringSize was NULL.

+

+**/

 EFI_STATUS

 EFIAPI

 HiiLibGetString (

@@ -201,6 +279,24 @@ HiiLibGetString (
 }

 

 

+/**

+  Get string specified by StringId form the HiiHandle. The caller

+  is responsible to free the *String.

+

+  If String is NULL, then ASSERT.

+  If HiiHandle could not be found in the default HII database, then ASSERT.

+  If StringId is not found in PackageList, then ASSERT.

+

+  @param  HiiHandle              The HII handle of package list.

+  @param  StringId               The String ID.

+  @param  String                 The output string.

+

+  @retval EFI_NOT_FOUND          String is not found.

+  @retval EFI_SUCCESS            Operation is successful.

+  @retval EFI_OUT_OF_RESOURCES   There is not enought memory in the system.

+  @retval EFI_INVALID_PARAMETER  The String is NULL.

+

+**/

 EFI_STATUS

 EFIAPI

 HiiLibGetStringFromHandle (

diff --git a/MdePkg/Library/HiiLib/InternalHiiLib.h b/MdePkg/Library/HiiLib/InternalHiiLib.h
index 5d03cd1b78..c01e5b020a 100644
--- a/MdePkg/Library/HiiLib/InternalHiiLib.h
+++ b/MdePkg/Library/HiiLib/InternalHiiLib.h
@@ -41,12 +41,26 @@ extern CONST EFI_HII_STRING_PROTOCOL           *mHiiStringProt;
 extern BOOLEAN                           mHiiProtocolsInitialized;

 

 

+/**

+  This function check if the Hii Handle is a valid handle registered

+  in the HII database.

+

+  @param HiiHandle The HII Handle.

+

+  @retval TRUE If it is a valid HII handle.

+  @retval FALSE If it is a invalid HII handle.

+**/

 BOOLEAN

 IsHiiHandleRegistered (

   EFI_HII_HANDLE    HiiHandle

   )

 ;

 

+/**

+

+  This function locate Hii relative protocols for later usage.

+

+**/

 VOID

 LocateHiiProtocols (

   VOID