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

11 files changed, 551 insertions, 62 deletions

diff --git a/MdePkg/Include/Library/HiiLib.h b/MdePkg/Include/Library/HiiLib.h
index 30c1fe0..ba22b01 100644
--- a/MdePkg/Include/Library/HiiLib.h
+++ b/MdePkg/Include/Library/HiiLib.h
@@ -178,7 +178,6 @@ HiiLibSetString (
   @retval EFI_INVALID_PARAMETER  The String or StringSize was NULL.

 

 **/

-

 EFI_STATUS

 EFIAPI

 HiiLibGetString (

diff --git a/MdePkg/Include/Library/IfrSupportLib.h b/MdePkg/Include/Library/IfrSupportLib.h
index fbfb676..f4f7a19 100644
--- a/MdePkg/Include/Library/IfrSupportLib.h
+++ b/MdePkg/Include/Library/IfrSupportLib.h
@@ -224,8 +224,8 @@ CreateGotoOpCode (
 /**
   Create EFI_IFR_ONE_OF_OPTION_OP opcode.
 
-  @param  QuestionId             Question ID
-  @param  OptionList             The list of Options.
+  @param  OptionCount            The number of options.
+  @param  OptionsList            The list of Options.
   @param  Type                   The data type.
   @param  Data                   Destination for the created opcode binary
 
@@ -287,7 +287,7 @@ CreateOneOfOpCode (
   @param  Prompt                 String ID for Prompt
   @param  Help                   String ID for Help
   @param  QuestionFlags          Flags in Question Header
-  @param  Flags                  Flags for ordered list opcode
+  @param  OrderedListFlags       Flags for ordered list opcode
   @param  DataType               Type for option value
   @param  MaxContainers          Maximum count for options in this ordered list
   @param  OptionsList            List of options
@@ -308,7 +308,7 @@ CreateOrderedListOpCode (
   IN      EFI_STRING_ID       Prompt,
   IN      EFI_STRING_ID       Help,
   IN      UINT8               QuestionFlags,
-  IN      UINT8               Flags,
+  IN      UINT8               OrderedListFlags,
   IN      UINT8               DataType,
   IN      UINT8               MaxContainers,
   IN      IFR_OPTION          *OptionsList,
diff --git a/MdePkg/Library/HiiLib/HiiLanguage.c b/MdePkg/Library/HiiLib/HiiLanguage.c
index cd2b660..f5c8f03 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 b0c28e2..749b004 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 7be7f16..05e9aa8 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 5d03cd1..c01e5b0 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

diff --git a/MdePkg/Library/IfrSupportLib/IfrSupportLib.inf b/MdePkg/Library/IfrSupportLib/IfrSupportLib.inf
index cb5b53a..32e1027 100644
--- a/MdePkg/Library/IfrSupportLib/IfrSupportLib.inf
+++ b/MdePkg/Library/IfrSupportLib/IfrSupportLib.inf
@@ -1,7 +1,7 @@
 #/** @file

-# Component name for module UefiEfiIfrSupportLib

+#Utility functions which helps in opcode creation, HII configuration string manipulations, 

+#pop up window creations, setup browser persistence data set and get.

 #

-# FIX ME!

 # Copyright (c) 2007, Intel Corporation. All rights reserved.

 #

 #  All rights reserved. This program and the accompanying materials

diff --git a/MdePkg/Library/IfrSupportLib/UefiIfrCommon.c b/MdePkg/Library/IfrSupportLib/UefiIfrCommon.c
index 958400f..18c594f 100644
--- a/MdePkg/Library/IfrSupportLib/UefiIfrCommon.c
+++ b/MdePkg/Library/IfrSupportLib/UefiIfrCommon.c
@@ -1,6 +1,8 @@
 /** @file
+Utility functions which helps in opcode creation, HII configuration string manipulations, 
+pop up window creations, setup browser persistence data set and get.
 
-Copyright (c) 2007, Intel Corporation
+Copyright (c) 2007 - 2008, Intel Corporation
 All rights reserved. This program and the accompanying materials
 are licensed and made available under the terms and conditions of the BSD License
 which accompanies this distribution.  The full text of the license may be found at
@@ -9,15 +11,6 @@ http://opensource.org/licenses/bsd-license.php
 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 
-Module Name:
-
-  UefiIfrCommon.c
-
-Abstract:
-
-  Common Library Routines to assist handle HII elements.
-
-
 **/
 
 #include "UefiIfrLibraryInternal.h"
@@ -26,6 +19,17 @@ EFI_HII_DATABASE_PROTOCOL *gIfrLibHiiDatabase;
 EFI_HII_STRING_PROTOCOL   *gIfrLibHiiString;
 
 
+/**
+  IfrSupportLib's constructor. It locates the required protocol:
+  gEfiHiiDatabaseProtocolGuid and gEfiHiiStringProtocolGuid.
+
+  @param ImageHandle     The firmware allocated handle for the EFI image.
+  
+  @param SystemTable     A pointer to the EFI System Table.
+
+  @retval EFI_SUCCESS    This function always completes successfully.
+
+**/
 EFI_STATUS
 EFIAPI
 IfrSupportLibConstructor (
diff --git a/MdePkg/Library/IfrSupportLib/UefiIfrForm.c b/MdePkg/Library/IfrSupportLib/UefiIfrForm.c
index af43db0..d0da744 100644
--- a/MdePkg/Library/IfrSupportLib/UefiIfrForm.c
+++ b/MdePkg/Library/IfrSupportLib/UefiIfrForm.c
@@ -1,4 +1,6 @@
 /** @file
+Utility functions which helps in opcode creation, HII configuration string manipulations, 
+pop up window creations, setup browser persistence data set and get.
 
 Copyright (c) 2007- 2008, Intel Corporation
 All rights reserved. This program and the accompanying materials
@@ -9,15 +11,6 @@ http://opensource.org/licenses/bsd-license.php
 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 
-Module Name:
-
-  UefiIfrForm.c
-
-Abstract:
-
-  Common Library Routines to assist handle HII elements.
-
-
 **/
 
 #include "UefiIfrLibraryInternal.h"
@@ -223,7 +216,7 @@ IfrLibCreatePopUp (
 
 
 /**
-  Swap bytes in the buffer.
+  Swap bytes in the buffer. This is a internal function.
 
   @param  Buffer                 Binary buffer.
   @param  BufferSize             Size of the buffer in bytes.
@@ -231,7 +224,6 @@ IfrLibCreatePopUp (
   @return None.
 
 **/
-STATIC
 VOID
 SwapBuffer (
   IN OUT UINT8     *Buffer,
@@ -252,11 +244,10 @@ SwapBuffer (
 
 /**
   Converts the unicode character of the string from uppercase to lowercase.
+  This is a internal function.
 
   @param Str     String to be converted
 
-  @retval VOID
-  
 **/
 VOID
 ToLower (
diff --git a/MdePkg/Library/IfrSupportLib/UefiIfrLibraryInternal.h b/MdePkg/Library/IfrSupportLib/UefiIfrLibraryInternal.h
index dade859..34a0cf1 100644
--- a/MdePkg/Library/IfrSupportLib/UefiIfrLibraryInternal.h
+++ b/MdePkg/Library/IfrSupportLib/UefiIfrLibraryInternal.h
@@ -1,4 +1,6 @@
 /** @file
+Utility functions which helps in opcode creation, HII configuration string manipulations, 
+pop up window creations, setup browser persistence data set and get.
 
 Copyright (c) 2007, Intel Corporation
 All rights reserved. This program and the accompanying materials
@@ -9,19 +11,11 @@ http://opensource.org/licenses/bsd-license.php
 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 
-Module Name:
-
-  UefiIfrLibraryInternal
-
-Abstract:
-
-  The file contain all library function for Ifr Operations.
-
 
 **/
 
-#ifndef _IFRLIBRARY_INTERNAL_H
-#define _IFRLIBRARY_INTERNAL_H
+#ifndef _IFRLIBRARY_INTERNAL_H_
+#define _IFRLIBRARY_INTERNAL_H_
 
 
 #include <PiDxe.h>
@@ -41,3 +35,4 @@ Abstract:
 #include <Library/PcdLib.h>
 
 #endif
+
diff --git a/MdePkg/Library/IfrSupportLib/UefiIfrOpCodeCreation.c b/MdePkg/Library/IfrSupportLib/UefiIfrOpCodeCreation.c
index f2f82e0..b4cba78 100644
--- a/MdePkg/Library/IfrSupportLib/UefiIfrOpCodeCreation.c
+++ b/MdePkg/Library/IfrSupportLib/UefiIfrOpCodeCreation.c
@@ -1,4 +1,7 @@
 /** @file
+  Library Routines to create IFR independent of string data - assume tokens already exist
+  Primarily to be used for exporting op-codes at a label in pre-defined forms.
+
 
 Copyright (c) 2007, Intel Corporation
 All rights reserved. This program and the accompanying materials
@@ -9,32 +12,40 @@ http://opensource.org/licenses/bsd-license.php
 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 
-Module Name:
-
-  UefiIfrOpCodeCreation.c
 
-Abstract:
+**/
 
-  Library Routines to create IFR independent of string data - assume tokens already exist
-  Primarily to be used for exporting op-codes at a label in pre-defined forms.
+#include "UefiIfrLibraryInternal.h"
 
-Revision History:
+/**
+  Check if the input question flags is a valid value.
+  The valid combination of question flags includes
+  EFI_IFR_FLAG_READ_ONLY | EFI_IFR_FLAG_CALLBACK | EFI_IFR_FLAG_RESET_REQUIRED | EFI_IFR_FLAG_OPTIONS_ONLY.
 
+  @param Flags The question flags to check.
 
+  @retval TRUE  If the question flag is a valid combination.
+  @retval FALSE If the question flag is an invalid combination.
+  
 **/
-
-#include "UefiIfrLibraryInternal.h"
-
-STATIC
 BOOLEAN
 IsValidQuestionFlags (
   IN UINT8                   Flags
   )
 {
-  return (BOOLEAN) ((Flags & (~QUESTION_FLAGS)) ? FALSE : TRUE);
+  return (BOOLEAN) (((Flags & (~QUESTION_FLAGS)) != 0) ? FALSE : TRUE);
 }
 
-STATIC
+/**
+  Check if the input value type is a valid type.
+  The valid value type is smaller or equal than EFI_IFR_TYPE_OTHER.
+
+  @param Type   The value type to check.
+
+  @retval TRUE  If the value type is valid.
+  @retval FALSE If the value type is invalid.
+  
+**/
 BOOLEAN
 IsValidValueType (
   IN UINT8                   Type
@@ -43,13 +54,21 @@ IsValidValueType (
   return (BOOLEAN) ((Type <= EFI_IFR_TYPE_OTHER) ? TRUE : FALSE);
 }
 
-STATIC
+/**
+  Check if the input numeric flags is a valid value.
+
+  @param Flags The numeric flags to check.
+
+  @retval TRUE  If the numeric flags is valid.
+  @retval FALSE If the numeric flags is invalid.
+  
+**/
 BOOLEAN
 IsValidNumricFlags (
   IN UINT8                   Flags
   )
 {
-  if (Flags & ~(EFI_IFR_NUMERIC_SIZE | EFI_IFR_DISPLAY)) {
+  if ((Flags & ~(EFI_IFR_NUMERIC_SIZE | EFI_IFR_DISPLAY)) != 0) {
     return FALSE;
   }
 
@@ -60,7 +79,15 @@ IsValidNumricFlags (
   return TRUE;
 }
 
-STATIC
+/**
+  Check if the checkbox flags is a valid value.
+
+  @param Flags The checkbox flags to check.
+
+  @retval TRUE  If the checkbox flags is valid.
+  @retval FALSE If the checkbox flags is invalid.
+  
+**/
 BOOLEAN
 IsValidCheckboxFlags (
   IN UINT8                   Flags
@@ -69,6 +96,17 @@ IsValidCheckboxFlags (
   return (BOOLEAN) ((Flags <= EFI_IFR_CHECKBOX_DEFAULT_MFG) ? TRUE : FALSE);
 }
 
+/**
+  Create EFI_IFR_END_OP opcode.
+
+  If Data is NULL or Data->Data is NULL, then ASSERT.
+
+  @param  Data                   Destination for the created opcode binary
+
+  @retval EFI_SUCCESS            Opcode create success
+  @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
+
+**/
 EFI_STATUS
 EFIAPI
 CreateEndOpCode (
@@ -95,6 +133,18 @@ CreateEndOpCode (
   return EFI_SUCCESS;
 }
 
+/**
+  Create EFI_IFR_DEFAULT_OP opcode.
+
+  @param  Value                  Value for the default
+  @param  Type                   Type for the default
+  @param  Data                   Destination for the created opcode binary
+
+  @retval EFI_SUCCESS            Opcode create success
+  @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
+  @retval EFI_INVALID_PARAMETER The type is not valid.
+
+**/
 EFI_STATUS
 EFIAPI
 CreateDefaultOpCode (
@@ -130,6 +180,21 @@ CreateDefaultOpCode (
   return EFI_SUCCESS;
 }
 
+/**
+  Create EFI_IFR_ACTION_OP opcode.
+
+  @param  QuestionId             Question ID
+  @param  Prompt                 String ID for Prompt
+  @param  Help                   String ID for Help
+  @param  QuestionFlags          Flags in Question Header
+  @param  QuestionConfig         String ID for configuration
+  @param  Data                   Destination for the created opcode binary
+
+  @retval EFI_SUCCESS            Opcode create success
+  @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
+  @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
+
+**/
 EFI_STATUS
 EFIAPI
 CreateActionOpCode (
@@ -171,6 +236,19 @@ CreateActionOpCode (
   return EFI_SUCCESS;
 }
 
+/**
+  Create EFI_IFR_SUBTITLE_OP opcode.
+
+  @param  Prompt                 String ID for Prompt
+  @param  Help                   String ID for Help
+  @param  Flags                  Subtitle opcode flags
+  @param  Scope                  Subtitle Scope bit
+  @param  Data                   Destination for the created opcode binary
+
+  @retval EFI_SUCCESS            Opcode create success
+  @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
+  
+**/
 EFI_STATUS
 EFIAPI
 CreateSubTitleOpCode (
@@ -205,6 +283,18 @@ CreateSubTitleOpCode (
 }
 
 
+/**
+  Create EFI_IFR_TEXT_OP opcode.
+
+  @param  Prompt                 String ID for Prompt
+  @param  Help                   String ID for Help
+  @param  TextTwo                String ID for text two
+  @param  Data                   Destination for the created opcode binary
+
+  @retval EFI_SUCCESS            Opcode create success
+  @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
+
+**/
 EFI_STATUS
 EFIAPI
 CreateTextOpCode (
@@ -237,6 +327,21 @@ CreateTextOpCode (
   return EFI_SUCCESS;
 }
 
+/**
+  Create EFI_IFR_REF_OP opcode.
+
+  @param  FormId                 Destination Form ID
+  @param  Prompt                 String ID for Prompt
+  @param  Help                   String ID for Help
+  @param  QuestionFlags          Flags in Question Header
+  @param  QuestionId             Question ID
+  @param  Data                   Destination for the created opcode binary
+
+  @retval EFI_SUCCESS            Opcode create success
+  @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
+  @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
+
+**/
 EFI_STATUS
 EFIAPI
 CreateGotoOpCode (
@@ -278,6 +383,18 @@ CreateGotoOpCode (
   return EFI_SUCCESS;
 }
 
+/**
+  Create EFI_IFR_ONE_OF_OPTION_OP opcode.
+
+  @param  OptionCount            The number of options.
+  @param  OptionsList            The list of Options.
+  @param  Type                   The data type.
+  @param  Data                   Destination for the created opcode binary
+
+  @retval EFI_SUCCESS            Opcode create success
+  @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
+
+**/
 EFI_STATUS
 EFIAPI
 CreateOneOfOptionOpCode (
@@ -319,6 +436,25 @@ CreateOneOfOptionOpCode (
   return EFI_SUCCESS;
 }
 
+/**
+  Create EFI_IFR_ONE_OF_OP opcode.
+
+  @param  QuestionId             Question ID
+  @param  VarStoreId             Storage ID
+  @param  VarOffset              Offset in Storage
+  @param  Prompt                 String ID for Prompt
+  @param  Help                   String ID for Help
+  @param  QuestionFlags          Flags in Question Header
+  @param  OneOfFlags             Flags for oneof opcode
+  @param  OptionsList            List of options
+  @param  OptionCount            Number of options in option list
+  @param  Data                   Destination for the created opcode binary
+
+  @retval EFI_SUCCESS            Opcode create success
+  @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
+  @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
+
+**/
 EFI_STATUS
 EFIAPI
 CreateOneOfOpCode (
@@ -374,6 +510,27 @@ CreateOneOfOpCode (
   return EFI_SUCCESS;
 }
 
+/**
+  Create EFI_IFR_ORDERED_LIST_OP opcode.
+
+  @param  QuestionId             Question ID
+  @param  VarStoreId             Storage ID
+  @param  VarOffset              Offset in Storage
+  @param  Prompt                 String ID for Prompt
+  @param  Help                   String ID for Help
+  @param  QuestionFlags          Flags in Question Header
+  @param  OrderedListFlags       Flags for ordered list opcode
+  @param  DataType               Type for option value
+  @param  MaxContainers          Maximum count for options in this ordered list
+  @param  OptionsList            List of options
+  @param  OptionCount            Number of options in option list
+  @param  Data                   Destination for the created opcode binary
+
+  @retval EFI_SUCCESS            Opcode create success
+  @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
+  @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
+
+**/
 EFI_STATUS
 EFIAPI
 CreateOrderedListOpCode (
@@ -436,6 +593,23 @@ CreateOrderedListOpCode (
   return EFI_SUCCESS;
 }
 
+/**
+  Create EFI_IFR_CHECKBOX_OP opcode.
+
+  @param  QuestionId             Question ID
+  @param  VarStoreId             Storage ID
+  @param  VarOffset              Offset in Storage
+  @param  Prompt                 String ID for Prompt
+  @param  Help                   String ID for Help
+  @param  QuestionFlags          Flags in Question Header
+  @param  CheckBoxFlags          Flags for checkbox opcode
+  @param  Data                   Destination for the created opcode binary
+
+  @retval EFI_SUCCESS            Opcode create success
+  @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
+  @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
+
+**/
 EFI_STATUS
 EFIAPI
 CreateCheckBoxOpCode (
@@ -480,6 +654,27 @@ CreateCheckBoxOpCode (
   return EFI_SUCCESS;
 }
 
+/**
+  Create EFI_IFR_NUMERIC_OP opcode.
+
+  @param  QuestionId             Question ID
+  @param  VarStoreId             Storage ID
+  @param  VarOffset              Offset in Storage
+  @param  Prompt                 String ID for Prompt
+  @param  Help                   String ID for Help
+  @param  QuestionFlags          Flags in Question Header
+  @param  NumericFlags           Flags for numeric opcode
+  @param  Minimum                Numeric minimum value
+  @param  Maximum                Numeric maximum value
+  @param  Step                   Numeric step for edit
+  @param  Default                Numeric default value
+  @param  Data                   Destination for the created opcode binary
+
+  @retval EFI_SUCCESS            Opcode create success
+  @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
+  @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
+
+**/
 EFI_STATUS
 EFIAPI
 CreateNumericOpCode (
@@ -567,6 +762,25 @@ CreateNumericOpCode (
   return EFI_SUCCESS;
 }
 
+/**
+  Create EFI_IFR_STRING_OP opcode.
+
+  @param  QuestionId             Question ID
+  @param  VarStoreId             Storage ID
+  @param  VarOffset              Offset in Storage
+  @param  Prompt                 String ID for Prompt
+  @param  Help                   String ID for Help
+  @param  QuestionFlags          Flags in Question Header
+  @param  StringFlags            Flags for string opcode
+  @param  MinSize                String minimum length
+  @param  MaxSize                String maximum length
+  @param  Data                   Destination for the created opcode binary
+
+  @retval EFI_SUCCESS            Opcode create success
+  @retval EFI_BUFFER_TOO_SMALL The space reserved in Data field is too small.
+  @retval EFI_INVALID_PARAMETER If QuestionFlags is not valid.
+
+**/
 EFI_STATUS
 EFIAPI
 CreateStringOpCode (
@@ -587,7 +801,7 @@ CreateStringOpCode (
 
   ASSERT (Data != NULL && Data->Data != NULL);
 
-  if (!IsValidQuestionFlags (QuestionFlags) || (StringFlags & (~EFI_IFR_STRING_MULTI_LINE))) {
+  if (!IsValidQuestionFlags (QuestionFlags) || (StringFlags & ~EFI_IFR_STRING_MULTI_LINE) != 0) {
     return EFI_INVALID_PARAMETER;
   }