From 48de23e54828456f8c4c8ec7e21288201c2de107 Mon Sep 17 00:00:00 2001
From: Nhi Pham <nhi@os.amperecomputing.com>
Date: Wed, 6 Jan 2021 23:09:00 +0700
Subject: [PATCH] EmbeddedPkg/TimeBaseLib: Update comment blocks for API
 functions

This updates Doxygen comment blocks for API library functions.

Cc: Leif Lindholm <leif@nuviainc.com>
Cc: Ard Biesheuvel <ard.biesheuvel@arm.com>
Signed-off-by: Nhi Pham <nhi@os.amperecomputing.com>
Reviewed-by: Leif Lindholm <leif@nuviainc.com>
---
 EmbeddedPkg/Include/Library/TimeBaseLib.h     | 54 ++++++++++++++--
 EmbeddedPkg/Library/TimeBaseLib/TimeBaseLib.c | 64 ++++++++++++++++---
 2 files changed, 104 insertions(+), 14 deletions(-)

diff --git a/EmbeddedPkg/Include/Library/TimeBaseLib.h b/EmbeddedPkg/Include/Library/TimeBaseLib.h
index 90853c3f4b..a9f3c6588b 100644
--- a/EmbeddedPkg/Include/Library/TimeBaseLib.h
+++ b/EmbeddedPkg/Include/Library/TimeBaseLib.h
@@ -2,6 +2,7 @@
 *
 *  Copyright (c) 2016, Hisilicon Limited. All rights reserved.
 *  Copyright (c) 2016-2019, Linaro Limited. All rights reserved.
+*  Copyright (c) 2021, Ampere Computing LLC. All rights reserved.
 *
 *  SPDX-License-Identifier: BSD-2-Clause-Patent
 *
@@ -52,18 +53,45 @@
 #define SEC_PER_HOUR                                    ((UINTN)  3600)
 #define SEC_PER_DAY                                     ((UINTN) 86400)
 
+/**
+  Check if it is a leap year.
+
+  @param    Time  The UEFI time to be checked.
+
+  @retval   TRUE  It is a leap year.
+  @retval   FALSE It is NOT a leap year.
+
+**/
 BOOLEAN
 EFIAPI
 IsLeapYear (
   IN  EFI_TIME  *Time
   );
 
+/**
+  Check if the day in the UEFI time is valid.
+
+  @param    Time    The UEFI time to be checked.
+
+  @retval   TRUE    Valid.
+  @retval   FALSE   Invalid.
+
+**/
 BOOLEAN
 EFIAPI
 IsDayValid (
   IN  EFI_TIME  *Time
   );
 
+/**
+  Check if the UEFI time is valid.
+
+  @param    Time    The UEFI time to be checked.
+
+  @retval   TRUE    Valid.
+  @retval   FALSE   Invalid.
+
+**/
 BOOLEAN
 EFIAPI
 IsTimeValid (
@@ -71,8 +99,12 @@ IsTimeValid (
   );
 
 /**
-  Converts Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC) to EFI_TIME
- **/
+  Converts Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC) to EFI_TIME.
+
+  @param  EpochSeconds   Epoch seconds.
+  @param  Time           The time converted to UEFI format.
+
+**/
 VOID
 EFIAPI
 EpochToEfiTime (
@@ -81,8 +113,13 @@ EpochToEfiTime (
   );
 
 /**
-  Converts EFI_TIME to Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC)
- **/
+  Converts EFI_TIME to Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC).
+
+  @param    Time  The UEFI time to be converted.
+
+  @return   Number of seconds.
+
+**/
 UINTN
 EFIAPI
 EfiTimeToEpoch (
@@ -90,8 +127,13 @@ EfiTimeToEpoch (
   );
 
 /**
-  returns Day of the week [0-6] 0=Sunday
- **/
+  Get the day of the week from the UEFI time.
+
+  @param    Time  The UEFI time to be calculated.
+
+  @return   The day of the week: Sunday=0, Monday=1, ... Saturday=6
+
+**/
 UINTN
 EfiTimeToWday (
   IN  EFI_TIME  *Time
diff --git a/EmbeddedPkg/Library/TimeBaseLib/TimeBaseLib.c b/EmbeddedPkg/Library/TimeBaseLib/TimeBaseLib.c
index 78fc7b6cd2..c9048d7659 100644
--- a/EmbeddedPkg/Library/TimeBaseLib/TimeBaseLib.c
+++ b/EmbeddedPkg/Library/TimeBaseLib/TimeBaseLib.c
@@ -2,6 +2,7 @@
 *
 *  Copyright (c) 2016, Hisilicon Limited. All rights reserved.
 *  Copyright (c) 2016-2019, Linaro Limited. All rights reserved.
+*  Copyright (c) 2021, Ampere Computing LLC. All rights reserved.
 *
 *  SPDX-License-Identifier: BSD-2-Clause-Patent
 *
@@ -13,8 +14,12 @@
 #include <Library/TimeBaseLib.h>
 
 /**
-  Converts Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC) to EFI_TIME
- **/
+  Converts Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC) to EFI_TIME.
+
+  @param  EpochSeconds   Epoch seconds.
+  @param  Time           The time converted to UEFI format.
+
+**/
 VOID
 EFIAPI
 EpochToEfiTime (
@@ -71,8 +76,13 @@ EpochToEfiTime (
 }
 
 /**
-  Calculate Epoch days
- **/
+  Calculate Epoch days.
+
+  @param    Time  The UEFI time to be calculated.
+
+  @return   Number of days.
+
+**/
 UINTN
 EFIAPI
 EfiGetEpochDays (
@@ -96,9 +106,15 @@ EfiGetEpochDays (
 
   return EpochDays;
 }
+
 /**
-  Converts EFI_TIME to Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC)
- **/
+  Converts EFI_TIME to Epoch seconds (elapsed since 1970 JANUARY 01, 00:00:00 UTC).
+
+  @param    Time  The UEFI time to be converted.
+
+  @return   Number of seconds.
+
+**/
 UINTN
 EFIAPI
 EfiTimeToEpoch (
@@ -116,8 +132,13 @@ EfiTimeToEpoch (
 }
 
 /**
-  returns Day of the week [0-6] 0=Sunday
- **/
+  Get the day of the week from the UEFI time.
+
+  @param    Time  The UEFI time to be calculated.
+
+  @return   The day of the week: Sunday=0, Monday=1, ... Saturday=6
+
+**/
 UINTN
 EfiTimeToWday (
   IN  EFI_TIME  *Time
@@ -132,6 +153,15 @@ EfiTimeToWday (
   return (EpochDays + 4) % 7;
 }
 
+/**
+  Check if it is a leap year.
+
+  @param    Time  The UEFI time to be checked.
+
+  @retval   TRUE  It is a leap year.
+  @retval   FALSE It is NOT a leap year.
+
+**/
 BOOLEAN
 EFIAPI
 IsLeapYear (
@@ -153,6 +183,15 @@ IsLeapYear (
   }
 }
 
+/**
+  Check if the day in the UEFI time is valid.
+
+  @param    Time    The UEFI time to be checked.
+
+  @retval   TRUE    Valid.
+  @retval   FALSE   Invalid.
+
+**/
 BOOLEAN
 EFIAPI
 IsDayValid (
@@ -171,6 +210,15 @@ IsDayValid (
   return TRUE;
 }
 
+/**
+  Check if the UEFI time is valid.
+
+  @param    Time    The UEFI time to be checked.
+
+  @retval   TRUE    Valid.
+  @retval   FALSE   Invalid.
+
+**/
 BOOLEAN
 EFIAPI
 IsTimeValid(
-- 
2.39.2