Refine function comments for BdsDxe module.

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

MdeModulePkg/Universal/BdsDxe/BootMaint/ConsoleOption.c

@@ -18,7 +18,6 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
   Function creates a device path data structure that identically matches the
   device path passed in.
 
-
   @param DevPath         A pointer to a device path data structure.
 
   @return        The new copy of DevPath is created to identically match the input.
@@ -33,7 +32,6 @@ DevicePathInstanceDup (
 /**
   Update Com Ports attributes from DevicePath
 
-
   @param DevicePath      DevicePath that contains Com ports
 
   @retval EFI_SUCCESS   The update is successful.

MdeModulePkg/Universal/BdsDxe/BootMaint/FileExplorer.c

@@ -232,7 +232,7 @@ UpdateFileExplorer (
   @retval  EFI_OUT_OF_RESOURCES  Not enough storage is available to hold the variable and its data.
   @retval  EFI_DEVICE_ERROR      The variable could not be saved.
   @retval  EFI_UNSUPPORTED       The specified Action is not supported by the callback.
-
+  @retval  EFI_INVALID_PARAMETER If paramter Value or ActionRequest is NULL.
 **/
 EFI_STATUS
 EFIAPI
@@ -259,7 +259,7 @@ FileExplorerCallback (
   *ActionRequest = EFI_BROWSER_ACTION_REQUEST_NONE;
 
   //
-  // Retrive uncommitted data from Form Browser
+  // Retrieve uncommitted data from Form Browser
   //
   NvRamMap = &Private->FeFakeNvData;
   BufferSize = sizeof (FILE_EXPLORER_NV_DATA);

MdeModulePkg/Universal/BdsDxe/BootMaint/UpdatePage.c

@@ -114,11 +114,9 @@ UpdatePageEnd (
 }
 
 /**
-  Clean up the dynamic opcode at label and form specified by
+  Clean up the dynamic opcode at label and form specified by both LabelId. 
-  both LabelId. 
 
-  @param LabelId         It is both the Form ID and Label ID for
+  @param LabelId         It is both the Form ID and Label ID for opcode deletion.
-                         opcode deletion.
   @param CallbackData    The BMM context data.
 
 **/
@@ -150,7 +148,7 @@ CleanUpPage (
                          of the file to be boot from.
 
   @retval EFI_SUCCESS    The function completed successfull.
-  @return                 Other value if the boot from the file fails.
+  @return Other value if the boot from the file fails.
 
 **/
 EFI_STATUS
@@ -163,7 +161,7 @@ BootThisFile (
   CHAR16            *ExitData;
   BDS_COMMON_OPTION *Option;
 
-  Status                  = gBS->AllocatePool (EfiBootServicesData, sizeof (BDS_COMMON_OPTION), (VOID **) &Option);
+  Option = (BDS_COMMON_OPTION *) AllocatePool (sizeof (BDS_COMMON_OPTION));
   Option->Description     = FileContext->FileName;
   Option->DevicePath      = FileContext->DevicePath;
   Option->LoadOptionsSize = 0;
@@ -562,7 +560,7 @@ UpdateOrderPage (
 
 /**
   Create the dynamic page to allow user to set
-  the "BootNext" vaule.
+  the "BootNext" value.
 
   @param CallbackData    The BMM context data.
 
@@ -633,8 +631,7 @@ UpdateBootNextPage (
 }
 
 /**
-  Create the dynamic page to allow user to set
+  Create the dynamic page to allow user to set the "TimeOut" value.
-  the "TimeOut" vaule.
 
   @param CallbackData    The BMM context data.
 
@@ -673,7 +670,7 @@ UpdateTimeOutPage (
 }
 
 /**
-  Refresh the text mode page
+  Refresh the text mode page.
 
   @param CallbackData    The BMM context data.
 
@@ -778,8 +775,7 @@ UpdateConModePage (
 }
 
 /**
-  Create the dynamic page which allows user to 
+  Create the dynamic page which allows user to set the property such as Baud Rate, Data Bits,
-  set the property such as Baud Rate, Data Bits,
   Parity, Stop Bits, Terminal Type.
 
   @param CallbackData    The BMM context data.

MdeModulePkg/Universal/BdsDxe/BootMaint/Variable.c

@@ -20,7 +20,8 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
   make sure BootOrder is in valid state.
 
   @retval EFI_SUCCESS   If all boot load option EFI Variables corresponding to  
-                        BM_LOAD_CONTEXT marked for deletion is deleted
+                        BM_LOAD_CONTEXT marked for deletion is deleted.
+  @retval EFI_NOT_FOUND If can not find the boot option want to be deleted.
   @return Others        If failed to update the "BootOrder" variable after deletion. 
 
 **/
@@ -176,7 +177,8 @@ Var_ChangeBootOrder (
   After deleting this Driver option, call Var_ChangeDriverOrder to
   make sure DriverOrder is in valid state.
 
-  @retval EFI_SUCCESS Load Option is successfully updated.
+  @retval EFI_SUCCESS       Load Option is successfully updated.
+  @retval EFI_NOT_FOUND     Fail to find the driver option want to be deleted.
   @return Other value than EFI_SUCCESS if failed to update "Driver Order" EFI
           Variable.
 
@@ -476,8 +478,7 @@ Var_UpdateConsoleOption (
   console device.
 
   @retval EFI_SUCCESS    The function complete successfully.
-  @return                The EFI variable can be saved. See gRT->SetVariable 
+  @return The EFI variable can not be saved. See gRT->SetVariable for detail return information.
-                         for detail return information.
 **/
 EFI_STATUS
 Var_UpdateConsoleInpOption (
@@ -492,8 +493,7 @@ Var_UpdateConsoleInpOption (
   console device.
 
   @retval EFI_SUCCESS    The function complete successfully.
-  @return                The EFI variable can be saved. See gRT->SetVariable 
+  @return The EFI variable can not be saved. See gRT->SetVariable for detail return information.
-                         for detail return information.
 **/
 EFI_STATUS
 Var_UpdateConsoleOutOption (
@@ -508,8 +508,7 @@ Var_UpdateConsoleOutOption (
   console device.
 
   @retval EFI_SUCCESS    The function complete successfully.
-  @return                The EFI variable can be saved. See gRT->SetVariable 
+  @return The EFI variable can not be saved. See gRT->SetVariable for detail return information.  
-                         for detail return information.
 **/
 EFI_STATUS
 Var_UpdateErrorOutOption (
@@ -586,6 +585,7 @@ Var_UpdateDriverOption (
 
   NewMenuEntry = BOpt_CreateMenuEntry (BM_LOAD_CONTEXT_SELECT);
   if (NULL == NewMenuEntry) {
+    FreePool (Buffer);
     return EFI_OUT_OF_RESOURCES;
   }
 
@@ -1007,10 +1007,9 @@ Var_UpdateBootOrder (
 
   @param CallbackData    The BMM context data.
 
-  @retval EFI_SUCCESS    The function complete successfully.
+  @retval EFI_SUCCESS           The function complete successfully.
-  @retval EFI_SUCCESS    Not enough memory to complete the function.
+  @retval EFI_OUT_OF_RESOURCES  Not enough memory to complete the function.
-  @return                The EFI variable can be saved. See gRT->SetVariable 
+  @return The EFI variable can not be saved. See gRT->SetVariable for detail return information.
-                         for detail return information.
 
 **/
 EFI_STATUS
@@ -1076,9 +1075,9 @@ Var_UpdateDriverOrder (
 
   @param CallbackData    The context data for BMM.
 
-  @return EFI_SUCCESS    The function completed successfully.
+  @return EFI_SUCCESS           The function completed successfully.
-  @retval EFI_NOT_FOUND  If L"LegacyDevOrder" and EfiLegacyDevOrderGuid EFI Variable can be found.
+  @retval EFI_NOT_FOUND         If L"LegacyDevOrder" and EfiLegacyDevOrderGuid EFI Variable can be found.
-
+  @retval EFI_OUT_OF_RESOURCES  Fail to allocate memory resource
 **/
 EFI_STATUS
 Var_UpdateBBSOption (
@@ -1169,7 +1168,7 @@ Var_UpdateBBSOption (
                         &VarSize
                         );
 
-  if (NULL == VarData) {
+  if (VarData == NULL) {
     return EFI_NOT_FOUND;
   }
 
@@ -1192,7 +1191,7 @@ Var_UpdateBBSOption (
   }
 
   NewOrder = (UINT16 *) AllocateZeroPool (DevOrder->Length - sizeof (UINT16));
-  if (NULL == NewOrder) {
+  if (NewOrder == NULL) {
     FreePool (VarData);
     return EFI_OUT_OF_RESOURCES;
   }
@@ -1243,7 +1242,7 @@ Var_UpdateBBSOption (
   //
   BootOptionVar = GetLegacyBootOptionVar (CallbackData->BbsType, &Index, &OptionSize);
 
-  if (NULL != BootOptionVar) {
+  if (BootOptionVar != NULL) {
     CopyMem (
       DescString,
       LegacyDeviceContext->Description,
@@ -1263,7 +1262,7 @@ Var_UpdateBBSOption (
 
     Attribute = (UINT32 *) Ptr;
     *Attribute |= LOAD_OPTION_ACTIVE;
-    if (0xFF == LegacyDev[0]) {
+    if (LegacyDev[0] == 0xFF) {
       //
       // Disable this legacy boot option
       //
@@ -1276,7 +1275,7 @@ Var_UpdateBBSOption (
     Ptr += StrSize ((CHAR16 *) Ptr);
 
     NewOptionPtr = AllocateZeroPool (NewOptionSize);
-    if (NULL == NewOptionPtr) {
+    if (NewOptionPtr == NULL) {
       return EFI_OUT_OF_RESOURCES;
     }
 

MdeModulePkg/Universal/BdsDxe/BootMngr/BootManager.c

@@ -1,5 +1,5 @@
 /** @file
-  The platform boot manager reference implement
+  The platform boot manager reference implementation
 
 Copyright (c) 2004 - 2008, Intel Corporation. <BR>
 All rights reserved. This program and the accompanying materials

MdeModulePkg/Universal/BdsDxe/Capsules.c

@@ -70,17 +70,16 @@ BdsLockFv (
   Then call the dispatcher to dispatch drivers from them. Finally, check
   the status of the updates.
 
+  This function should be called by BDS in case we need to do some
+  sort of processing even if there is no capsule to process. We
+  need to do this if an earlier update went away and we need to
+  clear the capsule variable so on the next reset PEI does not see it and
+  think there is a capsule available.
 
-  @param BootMode        - the current boot mode
+  @param BootMode                 the current boot mode
 
-  @retval  EFI_INVALID_PARAMETER  boot mode is not correct for an update
+  @retval EFI_INVALID_PARAMETER   boot mode is not correct for an update
-                                  Note:
+  @retval EFI_SUCCESS             There is no error when processing capsule
-                                  This function should be called by BDS in case we need to do some
-                                  sort of processing even if there is no capsule to process. We
-                                  need to do this if an earlier update went awry and we need to
-                                  clear the capsule variable so on the next reset PEI does not see it and
-                                  think there is a capsule available.
-  @retval EFI_SUCCESS There is no error when processing capsule
 
 **/
 EFI_STATUS

MdeModulePkg/Universal/BdsDxe/DeviceMngr/DeviceManager.c

@@ -1,5 +1,5 @@
 /** @file
-  The platform device manager reference implement
+  The platform device manager reference implementation
 
 Copyright (c) 2004 - 2008, Intel Corporation. <BR>
 All rights reserved. This program and the accompanying materials
@@ -44,7 +44,6 @@ DEVICE_MANAGER_MENU_ITEM  mDeviceManagerMenuItemTable[] = {
   Formset. The decision by user is saved to gCallbackKey for later processing. If
   user set VBIOS, the new value is saved to EFI variable.
 
-
   @param This            Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
   @param Action          Specifies the type of action taken by the browser.
   @param QuestionId      A unique value which is sent to the original exporting driver
@@ -163,7 +162,6 @@ InitializeDeviceManager (
 }
 
 /**
-
   Call the browser and display the device manager to allow user
   to configure the platform.
 
@@ -171,7 +169,7 @@ InitializeDeviceManager (
   section header for all class of devices, one-of opcode to set VBIOS.
   
   @retval  EFI_SUCCESS             Operation is successful.
-  @retval  Other values if failed to clean up the dynamic content from HII
+  @return  Other values if failed to clean up the dynamic content from HII
            database.
 
 **/
@@ -306,7 +304,7 @@ CallDeviceManager (
                   &gEfiGenericPlatformVariableGuid,
                   &VideoOptionSize
                   );
-  if (NULL == VideoOption) {
+  if (VideoOption == NULL) {
     gDeviceManagerPrivate.VideoBios = 0;
   } else {
     gDeviceManagerPrivate.VideoBios = VideoOption[0];

MdeModulePkg/Universal/BdsDxe/FrontPage.c

@@ -42,14 +42,14 @@ FRONT_PAGE_CALLBACK_DATA  gFrontPagePrivate = {
   or more named elements from the target driver.
 
 
-  @param This            - Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
+  @param This            Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
-  @param Request         - A null-terminated Unicode string in <ConfigRequest> format.
+  @param Request         A null-terminated Unicode string in <ConfigRequest> format.
-  @param Progress        - On return, points to a character in the Request string.
+  @param Progress        On return, points to a character in the Request string.
                          Points to the string's null terminator if request was successful.
                          Points to the most recent '&' before the first failing name/value
                          pair (or the beginning of the string if the failure is in the
                          first name/value pair) if the request was not successful.
-  @param Results         - A null-terminated Unicode string in <ConfigAltResp> format which
+  @param Results         A null-terminated Unicode string in <ConfigAltResp> format which
                          has all values filled in for the names in the Request string.
                          String to be allocated by the called function.
 
@@ -75,9 +75,9 @@ FakeExtractConfig (
   This function processes the results of changes in configuration.
 
 
-  @param This            - Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
+  @param This            Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
-  @param Configuration   - A null-terminated Unicode string in <ConfigResp> format.
+  @param Configuration   A null-terminated Unicode string in <ConfigResp> format.
-  @param Progress        - A pointer to a string filled in with the offset of the most
+  @param Progress        A pointer to a string filled in with the offset of the most
                          recent '&' before the first failing name/value pair (or the
                          beginning of the string if the failure is in the first
                          name/value pair) or the terminating NULL if all was successful.
@@ -102,13 +102,13 @@ FakeRouteConfig (
   This function processes the results of changes in configuration.
 
 
-  @param This            - Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
+  @param This            Points to the EFI_HII_CONFIG_ACCESS_PROTOCOL.
-  @param Action          - Specifies the type of action taken by the browser.
+  @param Action          Specifies the type of action taken by the browser.
-  @param QuestionId      - A unique value which is sent to the original exporting driver
+  @param QuestionId      A unique value which is sent to the original exporting driver
                          so that it can identify the type of data to expect.
-  @param Type            - The type of value for the question.
+  @param Type            The type of value for the question.
-  @param Value           - A pointer to the data being sent to the original exporting driver.
+  @param Value           A pointer to the data being sent to the original exporting driver.
-  @param ActionRequest   - On return, points to the action requested by the callback function.
+  @param ActionRequest   On return, points to the action requested by the callback function.
 
   @retval  EFI_SUCCESS           The callback successfully handled the action.
   @retval  EFI_OUT_OF_RESOURCES  Not enough storage is available to hold the variable and its data.
@@ -491,9 +491,9 @@ CallFrontPage (
   Acquire the string associated with the ProducerGuid and return it.
 
 
-  @param ProducerGuid    - The Guid to search the HII database for
+  @param ProducerGuid    The Guid to search the HII database for
-  @param Token           - The token value of the string to extract
+  @param Token           The token value of the string to extract
-  @param String          - The string that is extracted
+  @param String          The string that is extracted
 
   @retval  EFI_SUCCESS  The function returns EFI_SUCCESS always.
 
@@ -518,11 +518,8 @@ GetProducerString (
 /**
   Convert Processor Frequency Data to a string
 
-
+  @param ProcessorFrequency The frequency data to process
-  @param ProcessorFrequency - The frequency data to process
+  @param String             The string that is created
-  @param String          - The string that is created
-
-  @return VOID.
 
 **/
 VOID
@@ -559,9 +556,8 @@ ConvertProcessorToString (
 /**
   Convert Memory Size to a string.
 
-
+  @param MemorySize      The size of the memory to process
-  @param MemorySize      - The size of the memory to process
+  @param String          The string that is created
-  @param String          - The string that is created
 
 **/
 VOID
@@ -689,13 +685,11 @@ UpdateFrontPageStrings (
 /**
   Function waits for a given event to fire, or for an optional timeout to expire.
 
+  @param Event              The event to wait for
+  @param Timeout            An optional timeout value in 100 ns units.
 
-  @param Event           The event to wait for
+  @retval  EFI_SUCCESS      Event fired before Timeout expired.
-                        
+  @retval  EFI_TIME_OUT     Timout expired before Event fired..
-  @param Timeout         An optional timeout value in 100 ns units.
-
-  @retval  EFI_SUCCESS       Event fired before Timeout expired.
-  @retval  EFI_TIME_OUT      Timout expired before Event fired..
 
 **/
 EFI_STATUS
@@ -755,8 +749,7 @@ WaitForSingleEvent (
   Function show progress bar to wait for user input.
 
 
-  @param TimeoutDefault  - The fault time out value before the system
+  @param TimeoutDefault  The fault time out value before the system continue to boot.
-                         continue to boot.
 
   @retval  EFI_SUCCESS       User pressed some key except "Enter"
   @retval  EFI_TIME_OUT      Timout expired or user press "Enter"
@@ -850,12 +843,10 @@ ShowProgress (
   this is the platform reference part and can be customize.
 
 
-  @param TimeoutDefault  - The fault time out value before the system
+  @param TimeoutDefault     The fault time out value before the system
-                         continue to boot.
+                            continue to boot.
-  @param ConnectAllHappened - The indicater to check if the connect all have
+  @param ConnectAllHappened The indicater to check if the connect all have
-                         already happended.
+                            already happended.
-
-  @return VOID.
 
 **/
 VOID

MdeModulePkg/Universal/BdsDxe/Hotkey.c

@@ -23,10 +23,8 @@ VOID            *mHotkeyRegistration;
 
 
 /**
-
   Check if the Key Option is valid or not.
 
-
   @param KeyOption       The Hot Key Option to be checked.
 
   @retval  TRUE          The Hot Key Option is valid.
@@ -67,15 +65,14 @@ IsKeyOptionValid (
 }
 
 /**
-
   Create Key#### for the given hotkey.
 
-
   @param KeyOption       The Hot Key Option to be added.
   @param KeyOptionNumber The key option number for Key#### (optional).
 
   @retval  EFI_SUCCESS            Register hotkey successfully.
   @retval  EFI_INVALID_PARAMETER  The hotkey option is invalid.
+  @retval  EFI_OUT_OF_RESOURCES   Fail to allocate memory resource.
 
 **/
 EFI_STATUS
@@ -110,7 +107,6 @@ RegisterHotkey (
   //
   // check whether HotKey conflict with keys used by Setup Browser
   //
-
   KeyOrder = BdsLibGetVariableAndSize (
                VAR_KEY_ORDER,
                &gEfiGlobalVariableGuid,
@@ -187,7 +183,7 @@ RegisterHotkey (
                   KeyOption
                   );
   if (EFI_ERROR (Status)) {
-    gBS->FreePool (KeyOrder);
+    FreePool (KeyOrder);
     return Status;
   }
 
@@ -201,6 +197,7 @@ RegisterHotkey (
 
   NewKeyOrder = AllocatePool (KeyOrderSize);
   if (NewKeyOrder == NULL) {
+    FreePool (KeyOrder);
     return EFI_OUT_OF_RESOURCES;
   }
 
@@ -307,11 +304,10 @@ UnregisterHotkey (
   This is the common notification function for HotKeys, it will be registered
   with SimpleTextInEx protocol interface - RegisterKeyNotify() of ConIn handle.
 
-
   @param KeyData         A pointer to a buffer that is filled in with the keystroke
                          information for the key that was pressed.
 
-  @retval  EFI_SUCCESS            KeyData is successfully processed.
+  @retval  EFI_SUCCESS   KeyData is successfully processed.
 
 **/
 EFI_STATUS
@@ -427,10 +423,8 @@ HotkeyCallback (
 }
 
 /**
-
   Register the common HotKey notify function to given SimpleTextInEx protocol instance.
 
-
   @param SimpleTextInEx  Simple Text Input Ex protocol instance
 
   @retval  EFI_SUCCESS            Register hotkey notification function successfully.
@@ -481,12 +475,9 @@ HotkeyRegisterNotify (
 /**
   Callback function for SimpleTextInEx protocol install events
 
-
   @param Event           the event that is signaled.
   @param Context         not used here.
 
-  @return VOID
-
 **/
 VOID
 EFIAPI
@@ -528,14 +519,12 @@ HotkeyEvent (
 }
 
 /**
-
   Insert Key Option to hotkey list.
 
-
   @param KeyOption       The Hot Key Option to be added to hotkey list.
 
-  @retval  EFI_SUCCESS  Add to hotkey list success.
+  @retval EFI_SUCCESS           Add to hotkey list success.
-
+  @retval EFI_OUT_OF_RESOURCES  Fail to allocate memory resource.
 **/
 EFI_STATUS
 HotkeyInsertList (

MdeModulePkg/Universal/BdsDxe/HwErrRecSupport.c

@@ -22,10 +22,10 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 
 
   @param HwErrRecSupportLevel
-                         zero value      - Indicates that the platform implements no support for
+                         zero value:      Indicates that the platform implements no support for
-                         Hardware Error Record Persistence.
+                                          Hardware Error Record Persistence.
-                         non-zero value  - Indicates that the platform implements Hardware Error
+                         non-zero value:  Indicates that the platform implements Hardware Error
-                         Record Persistence.
+                                          Record Persistence.
 
 **/
 VOID