Add doxygen style comments for functions in English module.

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

2 files changed, 177 insertions, 141 deletions

diff --git a/MdeModulePkg/Universal/Disk/UnicodeCollation/EnglishDxe/UnicodeCollationEng.c b/MdeModulePkg/Universal/Disk/UnicodeCollation/EnglishDxe/UnicodeCollationEng.c
index 6d0b556561..07bb2f446d 100644
--- a/MdeModulePkg/Universal/Disk/UnicodeCollation/EnglishDxe/UnicodeCollationEng.c
+++ b/MdeModulePkg/Universal/Disk/UnicodeCollation/EnglishDxe/UnicodeCollationEng.c
@@ -1,5 +1,5 @@
 /** @file

-  Unicode Collation Protocol (English)

+  Driver to implement English version of Unicode Collation Protocol.

 

 Copyright (c) 2006 - 2008, Intel Corporation. <BR>

 All rights reserved. This program and the accompanying materials

@@ -79,33 +79,25 @@ GLOBAL_REMOVE_IF_UNREFERENCED EFI_UNICODE_COLLATION_PROTOCOL  Unicode2Eng = {
   "en"

 };

 

-//

-// Driver entry point.

-//

+/**

+  The user Entry Point for English module.

+ 

+  This function initializes unicode character mapping and then installs Unicode

+  Collation & Unicode Collation 2 Protocols based on the feature flags.  

+

+  @param  ImageHandle    The firmware allocated handle for the EFI image.  

+  @param  SystemTable    A pointer to the EFI System Table.

+  

+  @retval EFI_SUCCESS    The entry point is executed successfully.

+  @retval other          Some error occurs when executing this entry point.

+

+**/

 EFI_STATUS

 EFIAPI

 InitializeUnicodeCollationEng (

   IN EFI_HANDLE       ImageHandle,

   IN EFI_SYSTEM_TABLE *SystemTable

   )

-/*++

-

-Routine Description:

-

-  Initializes the Unicode Collation Driver

-

-Arguments:

-

-  ImageHandle -

-

-  SystemTable -

-

-Returns:

-

-  EFI_SUCCESS

-  EFI_OUT_OF_RESOURCES

-

---*/

 {

   EFI_STATUS  Status;

   UINTN       Index;

@@ -177,67 +169,55 @@ Returns:
   return Status;

 }

 

+

+/**

+  Performs a case-insensitive comparison of two Null-terminated Unicode 

+  strings.

+

+  @param  This Protocol instance pointer.

+  @param  Str1 A pointer to a Null-terminated Unicode string.

+  @param  Str2 A pointer to a Null-terminated Unicode string.

+

+  @retval 0   Str1 is equivalent to Str2

+  @retval > 0 Str1 is lexically greater than Str2

+  @retval < 0 Str1 is lexically less than Str2

+

+**/

 INTN

 EFIAPI

 EngStriColl (

   IN EFI_UNICODE_COLLATION_PROTOCOL   *This,

-  IN CHAR16                           *s1,

-  IN CHAR16                           *s2

+  IN CHAR16                           *Str1,

+  IN CHAR16                           *Str2

   )

-/*++

-

-Routine Description:

-

-  Performs a case-insensitive comparison of two Null-terminated Unicode strings.

-

-Arguments:

-

-  This

-  s1

-  s2

-

-Returns:

-

---*/

 {

-  while (*s1) {

-    if (ToUpper (*s1) != ToUpper (*s2)) {

+  while (*Str1) {

+    if (ToUpper (*Str1) != ToUpper (*Str2)) {

       break;

     }

 

-    s1 += 1;

-    s2 += 1;

+    Str1 += 1;

+    Str2 += 1;

   }

 

-  return ToUpper (*s1) - ToUpper (*s2);

+  return ToUpper (*Str1) - ToUpper (*Str2);

 }

 

+

+/**

+  Converts all the Unicode characters in a Null-terminated Unicode string to 

+  lower case Unicode characters.

+

+  @param  This   Protocol instance pointer.

+  @param  Str    A pointer to a Null-terminated Unicode string.

+

+**/

 VOID

 EFIAPI

 EngStrLwr (

   IN EFI_UNICODE_COLLATION_PROTOCOL   *This,

   IN OUT CHAR16                       *Str

   )

-/*++

-

-Routine Description:

-

-  Converts all the Unicode characters in a Null-terminated Unicode string

-  to lower case Unicode characters.

-

-Arguments:

-

-  This - A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.

-  Str1  - A pointer to a Null-terminated Unicode string.

-  Str2  - A pointer to a Null-terminated Unicode string.

-

-Returns:

-

-  0   - s1 is equivalent to s2.

-  > 0 - s1 is lexically greater than s2.

-  < 0 - s1 is lexically less than s2.

-

---*/

 {

   while (*Str) {

     *Str = ToLower (*Str);

@@ -245,27 +225,21 @@ Returns:
   }

 }

 

+

+/**

+  Converts all the Unicode characters in a Null-terminated Unicode string to upper

+  case Unicode characters.

+

+  @param  This   Protocol instance pointer.

+  @param  Str    A pointer to a Null-terminated Unicode string.

+

+**/

 VOID

 EFIAPI

 EngStrUpr (

   IN EFI_UNICODE_COLLATION_PROTOCOL   *This,

   IN OUT CHAR16                       *Str

   )

-/*++

-

-Routine Description:

-

-  Converts all the Unicode characters in a Null-terminated

-  Unicode string to upper case Unicode characters.

-

-Arguments:

-  This

-  Str

-

-Returns:

-  None

-

---*/

 {

   while (*Str) {

     *Str = ToUpper (*Str);

@@ -273,6 +247,18 @@ Returns:
   }

 }

 

+/**

+  Performs a case-insensitive comparison of a Null-terminated Unicode 

+  pattern string and a Null-terminated Unicode string.

+

+  @param  This    Protocol instance pointer.

+  @param  String  A pointer to a Null-terminated Unicode string.

+  @param  Pattern A pointer to a Null-terminated Unicode pattern string.

+

+  @retval TRUE    Pattern was found in String.

+  @retval FALSE   Pattern was not found in String.

+

+**/

 BOOLEAN

 EFIAPI

 EngMetaiMatch (

@@ -280,28 +266,6 @@ EngMetaiMatch (
   IN CHAR16                           *String,

   IN CHAR16                           *Pattern

   )

-/*++

-

-Routine Description:

-

-  Performs a case-insensitive comparison between a Null-terminated

-  Unicode pattern string and a Null-terminated Unicode string.

-

-  The pattern string can use the '?' wildcard to match any character,

-  and the '*' wildcard to match any sub-string.

-

-Arguments:

-

-  This     - A pointer to the EFI_UNICODE_COLLATION_PROTOCOL instance.

-  String   - A pointer to a Null-terminated Unicode string.

-  Pattern  - A pointer to a Null-terminated Unicode pattern string.

-

-Returns:

-

-  TRUE  - Pattern was found in String.

-  FALSE - Pattern was not found in String.

-

---*/

 {

   CHAR16  CharC;

   CHAR16  CharP;

@@ -419,6 +383,19 @@ Returns:
   }

 }

 

+

+/**

+  Converts an 8.3 FAT file name in an OEM character set to a Null-terminated 

+  Unicode string.

+

+  @param  This    Protocol instance pointer.

+  @param  FatSize The size of the string Fat in bytes.

+  @param  Fat     A pointer to a Null-terminated string that contains an 8.3 file

+                  name using an OEM character set.

+  @param  String  A pointer to a Null-terminated Unicode string. The string must

+                  be preallocated to hold FatSize Unicode characters.

+

+**/

 VOID

 EFIAPI

 EngFatToStr (

@@ -427,24 +404,6 @@ EngFatToStr (
   IN CHAR8                            *Fat,

   OUT CHAR16                          *String

   )

-/*++

-

-Routine Description:

-

-  Converts an 8.3 FAT file name using an OEM character set

-  to a Null-terminated Unicode string.

-

-  BUGBUG: Function has to expand DBCS FAT chars, currently not.

-

-Arguments:

-  This

-  FatSize

-  Fat

-  String

-

-Returns:

-

---*/

 {

   //

   // No DBCS issues, just expand and add null terminate to end of string

@@ -459,6 +418,22 @@ Returns:
   *String = 0;

 }

 

+

+/**

+  Converts a Null-terminated Unicode string to legal characters in a FAT 

+  filename using an OEM character set. 

+

+  @param  This    Protocol instance pointer.

+  @param  String  A pointer to a Null-terminated Unicode string. The string must

+                  be preallocated to hold FatSize Unicode characters.

+  @param  FatSize The size of the string Fat in bytes.

+  @param  Fat     A pointer to a Null-terminated string that contains an 8.3 file

+                  name using an OEM character set.

+

+  @retval TRUE    Fat is a Long File Name

+  @retval FALSE   Fat is an 8.3 file name

+

+**/

 BOOLEAN

 EFIAPI

 EngStrToFat (

@@ -467,26 +442,6 @@ EngStrToFat (
   IN UINTN                            FatSize,

   OUT CHAR8                           *Fat

   )

-/*++

-

-Routine Description:

-

-  Converts a Null-terminated Unicode string to legal characters

-  in a FAT filename using an OEM character set.

-

-  Functions has to crunch string to a fat string. Replacing

-  any chars that can't be represented in the fat name.

-

-Arguments:

-  This

-  String

-  FatSize

-  Fat

-

-Returns:

-  TRUE

-  FALSE

---*/

 {

   BOOLEAN SpecialCharExist;

 

diff --git a/MdeModulePkg/Universal/Disk/UnicodeCollation/EnglishDxe/UnicodeCollationEng.h b/MdeModulePkg/Universal/Disk/UnicodeCollation/EnglishDxe/UnicodeCollationEng.h
index 74e243c424..7cab7088cf 100644
--- a/MdeModulePkg/Universal/Disk/UnicodeCollation/EnglishDxe/UnicodeCollationEng.h
+++ b/MdeModulePkg/Universal/Disk/UnicodeCollation/EnglishDxe/UnicodeCollationEng.h
@@ -38,15 +38,40 @@ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
 //

 // Prototypes

 //

+/**

+  Performs a case-insensitive comparison of two Null-terminated Unicode 

+  strings.

+

+  @param  This Protocol instance pointer.

+  @param  Str1 A pointer to a Null-terminated Unicode string.

+  @param  Str2 A pointer to a Null-terminated Unicode string.

+

+  @retval 0   Str1 is equivalent to Str2

+  @retval > 0 Str1 is lexically greater than Str2

+  @retval < 0 Str1 is lexically less than Str2

+

+**/

 INTN

 EFIAPI

 EngStriColl (

   IN EFI_UNICODE_COLLATION_PROTOCOL           *This,

-  IN CHAR16                                   *s1,

-  IN CHAR16                                   *s2

+  IN CHAR16                                   *Str1,

+  IN CHAR16                                   *Str2

   )

 ;

 

+/**

+  Performs a case-insensitive comparison of a Null-terminated Unicode 

+  pattern string and a Null-terminated Unicode string.

+

+  @param  This    Protocol instance pointer.

+  @param  String  A pointer to a Null-terminated Unicode string.

+  @param  Pattern A pointer to a Null-terminated Unicode pattern string.

+

+  @retval TRUE    Pattern was found in String.

+  @retval FALSE   Pattern was not found in String.

+

+**/

 BOOLEAN

 EFIAPI

 EngMetaiMatch (

@@ -56,6 +81,14 @@ EngMetaiMatch (
   )

 ;

 

+/**

+  Converts all the Unicode characters in a Null-terminated Unicode string to 

+  lower case Unicode characters.

+

+  @param  This   Protocol instance pointer.

+  @param  Str    A pointer to a Null-terminated Unicode string.

+

+**/

 VOID

 EFIAPI

 EngStrLwr (

@@ -64,6 +97,14 @@ EngStrLwr (
   )

 ;

 

+/**

+  Converts all the Unicode characters in a Null-terminated Unicode string to upper

+  case Unicode characters.

+

+  @param  This   Protocol instance pointer.

+  @param  Str    A pointer to a Null-terminated Unicode string.

+

+**/

 VOID

 EFIAPI

 EngStrUpr (

@@ -72,6 +113,18 @@ EngStrUpr (
   )

 ;

 

+/**

+  Converts an 8.3 FAT file name in an OEM character set to a Null-terminated 

+  Unicode string.

+

+  @param  This    Protocol instance pointer.

+  @param  FatSize The size of the string Fat in bytes.

+  @param  Fat     A pointer to a Null-terminated string that contains an 8.3 file

+                  name using an OEM character set.

+  @param  String  A pointer to a Null-terminated Unicode string. The string must

+                  be preallocated to hold FatSize Unicode characters.

+

+**/

 VOID

 EFIAPI

 EngFatToStr (

@@ -82,6 +135,21 @@ EngFatToStr (
   )

 ;

 

+/**

+  Converts a Null-terminated Unicode string to legal characters in a FAT 

+  filename using an OEM character set. 

+

+  @param  This    Protocol instance pointer.

+  @param  String  A pointer to a Null-terminated Unicode string. The string must

+                  be preallocated to hold FatSize Unicode characters.

+  @param  FatSize The size of the string Fat in bytes.

+  @param  Fat     A pointer to a Null-terminated string that contains an 8.3 file

+                  name using an OEM character set.

+

+  @retval TRUE    Fat is a Long File Name

+  @retval FALSE   Fat is an 8.3 file name

+

+**/

 BOOLEAN

 EFIAPI

 EngStrToFat (

@@ -92,6 +160,19 @@ EngStrToFat (
   )

 ;

 

+/**

+  The user Entry Point for English module.

+ 

+  This function initializes unicode character mapping and then installs Unicode

+  Collation & Unicode Collation 2 Protocols based on the feature flags.  

+

+  @param  ImageHandle    The firmware allocated handle for the EFI image.  

+  @param  SystemTable    A pointer to the EFI System Table.

+  

+  @retval EFI_SUCCESS    The entry point is executed successfully.

+  @retval other          Some error occurs when executing this entry point.

+

+**/

 EFI_STATUS

 EFIAPI

 InitializeUnicodeCollationEng (