MdeModulePkg/UefiBootManagerLib: fix AddLoadOptionVariable docs/prototype

Clean up the leading comment and the prototype of
EfiBootManagerAddLoadOptionVariable():

- the function may modify Option on output, annotate the parameter with
  OUT and update the documentation;

- "@retval EFI_STATUS" and "@retval Others" are not idiomatic
  documentation, use @return instead;

- sync comment and prototype between lib instance and lib class header.

Change-Id: I8a609d6502b6f8929b2f568acaa147065003b6f4
Cc: Eric Dong <eric.dong@intel.com>
Cc: Ruiyu Ni <ruiyu.ni@intel.com>
Cc: Star Zeng <star.zeng@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Laszlo Ersek <lersek@redhat.com>
Reviewed-by: Ruiyu Ni <ruiyu.ni@intel.com>

diff --git a/MdeModulePkg/Include/Library/UefiBootManagerLib.h b/MdeModulePkg/Include/Library/UefiBootManagerLib.h
index 97ac1f233ce9489e7995931264f24f081ba64152..1d862a4b2684074264a6891351854712f8dd94fc 100644 (file)
--- a/MdeModulePkg/Include/Library/UefiBootManagerLib.h
+++ b/MdeModulePkg/Include/Library/UefiBootManagerLib.h
@@ -176,20 +176,30 @@ EfiBootManagerLoadOptionToVariable (
   );\r
 \r
 /**\r
-  This function will update the Boot####/Driver####/SysPrep#### and the \r
-  BootOrder/DriverOrder/SysPrepOrder to add a new load option.\r
+  This function will register the new Boot####, Driver#### or SysPrep#### option.\r
+  After the *#### is updated, the *Order will also be updated.\r
 \r
-  @param  Option        Pointer to load option to add.\r
-  @param  Position      Position of the new load option to put in the BootOrder/DriverOrder/SysPrepOrder.\r
+  @param  Option            Pointer to load option to add. If on input\r
+                            Option->OptionNumber is LoadOptionNumberUnassigned,\r
+                            then on output Option->OptionNumber is updated to\r
+                            the number of the new Boot####,\r
+                            Driver#### or SysPrep#### option.\r
+  @param  Position          Position of the new load option to put in the ****Order variable.\r
+\r
+  @retval EFI_SUCCESS           The *#### have been successfully registered.\r
+  @retval EFI_INVALID_PARAMETER The option number exceeds 0xFFFF.\r
+  @retval EFI_ALREADY_STARTED   The option number of Option is being used already.\r
+                                Note: this API only adds new load option, no replacement support.\r
+  @retval EFI_OUT_OF_RESOURCES  There is no free option number that can be used when the\r
+                                option number specified in the Option is LoadOptionNumberUnassigned.\r
+  @return                       Status codes of gRT->SetVariable ().\r
 \r
-  @retval EFI_SUCCESS   The load option has been successfully added.\r
-  @retval Others        Error status returned by RT->SetVariable.\r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
 EfiBootManagerAddLoadOptionVariable (\r
-  IN EFI_BOOT_MANAGER_LOAD_OPTION  *Option,\r
-  IN UINTN                         Position\r
+  IN OUT EFI_BOOT_MANAGER_LOAD_OPTION *Option,\r
+  IN     UINTN                        Position\r
   );\r
 \r
 /**\r

diff --git a/MdeModulePkg/Library/UefiBootManagerLib/BmLoadOption.c b/MdeModulePkg/Library/UefiBootManagerLib/BmLoadOption.c
index 32918caf324ccdc98893149ccd9be4fc5320c7fe..f88f8e02451c71ad75f7399bfe6f661aa504c3e3 100644 (file)
--- a/MdeModulePkg/Library/UefiBootManagerLib/BmLoadOption.c
+++ b/MdeModulePkg/Library/UefiBootManagerLib/BmLoadOption.c
@@ -329,7 +329,11 @@ BmAddOptionNumberToOrderVariable (
   This function will register the new Boot####, Driver#### or SysPrep#### option.\r
   After the *#### is updated, the *Order will also be updated.\r
 \r
-  @param  Option            Pointer to load option to add.\r
+  @param  Option            Pointer to load option to add. If on input\r
+                            Option->OptionNumber is LoadOptionNumberUnassigned,\r
+                            then on output Option->OptionNumber is updated to\r
+                            the number of the new Boot####,\r
+                            Driver#### or SysPrep#### option.\r
   @param  Position          Position of the new load option to put in the ****Order variable.\r
 \r
   @retval EFI_SUCCESS           The *#### have been successfully registered.\r
@@ -338,14 +342,14 @@ BmAddOptionNumberToOrderVariable (
                                 Note: this API only adds new load option, no replacement support.\r
   @retval EFI_OUT_OF_RESOURCES  There is no free option number that can be used when the\r
                                 option number specified in the Option is LoadOptionNumberUnassigned.\r
-  @retval EFI_STATUS            Return the status of gRT->SetVariable ().\r
+  @return                       Status codes of gRT->SetVariable ().\r
 \r
 **/\r
 EFI_STATUS\r
 EFIAPI\r
 EfiBootManagerAddLoadOptionVariable (\r
-  IN EFI_BOOT_MANAGER_LOAD_OPTION *Option,\r
-  IN UINTN                        Position\r
+  IN OUT EFI_BOOT_MANAGER_LOAD_OPTION *Option,\r
+  IN     UINTN                        Position\r
   )\r
 {\r
   EFI_STATUS                      Status;\r