Update or add comments to files and functions for use by Doxygen.

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

4 files changed, 236 insertions, 70 deletions

diff --git a/StdLib/LibC/Ctype/CClass.c b/StdLib/LibC/Ctype/CClass.c
index f350063352..1e1e0fdccb 100644
--- a/StdLib/LibC/Ctype/CClass.c
+++ b/StdLib/LibC/Ctype/CClass.c
@@ -1,140 +1,253 @@
 /** @file

-  Character classification and case conversion functions for <ctype.h>.

+  Character classification function implementations for <ctype.h>.

 

-  Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>

+  Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>

   This program and the accompanying materials are licensed and made available under

   the terms and conditions of the BSD License that accompanies this distribution.

   The full text of the license may be found at

-  http://opensource.org/licenses/bsd-license.php.

+  http://opensource.org/licenses/bsd-license.

 

   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

-

 **/

 #include  <LibConfig.h>

 

 #define NO_CTYPE_MACROS            // So that we don't define the classification macros

 #include  <ctype.h>

 

+/** Internal worker function for character classification.

+

+    Determines if a character is a member of a set of character classes.

+

+    @param[in]    _c      The character to be tested.

+    @param[in]    mask    A bitmapped specification of the character classes to

+                          test the character against.  These bits are defined

+                          in _ctype.h.

+

+    @retval   0         The character, _c, is NOT a member of the character classes specified by mask.

+    @retval   nonZero   The character, _c, IS a member of a specified character class.

+**/

 int

-__isCClass( int _c, unsigned int mask)

+__isCClass(

+  IN  int _c,

+  unsigned int mask

+  )

 {

   return ((_c < 0 || _c > 127) ? 0 : (_cClass[_c] & mask));

 }

 

-/**

+/** The isalnum function tests for any character for which isalpha or isdigit

+    is true.

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int isalnum(int c)

+int

+isalnum(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CD | _CU | _CL | _XA)));

 }

 

-/**

+/** The isalpha function tests for any character for which isupper or islower

+    is true, or any character that is one of a locale-specific set of

+    alphabetic characters for which none of iscntrl, isdigit, ispunct, or

+    isspace is true. In the "C" locale, isalpha returns true only for the

+    characters for which isupper or islower is true.

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int isalpha(int c)

+int

+isalpha(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CU | _CL | _XA)));

 }

 

-/**

+/** The iscntrl function tests for any control character.

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int iscntrl(int c)

+int

+iscntrl(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CC)));

 }

 

-/**

+/** The isdigit function tests for any decimal-digit character.

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int isdigit(int c)

+int

+isdigit(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CD)));

 }

 

-/**

+/** The isgraph function tests for any printing character except space (' ').

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int isgraph(int c)

+int

+isgraph(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CG)));

 }

 

-/**

+/** The islower function tests for any character that is a lowercase letter or

+    is one of a locale-specific set of characters for which none of iscntrl,

+    isdigit, ispunct, or isspace is true.  In the "C" locale, islower returns

+    true only for the lowercase letters.

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int islower(int c)

+int

+islower(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CL)));

 }

 

-/**

+/** The isprint function tests for any printing character including space (' ').

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int isprint(int c)

+int

+isprint(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CS | _CG)));

 }

 

-/**

+/** The ispunct function tests for any printing character that is one of a

+    locale-specific set of punctuation characters for which neither isspace nor

+    isalnum is true. In the "C" locale, ispunct returns true for every printing

+    character for which neither isspace nor isalnum is true.

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int ispunct(int c)

+int

+ispunct(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CP)));

 }

 

-/**

+/** The isspace function tests for any character that is a standard white-space

+    character or is one of a locale-specific set of characters for which

+    isalnum is false. The standard white-space characters are the following:

+    space (' '), form feed ('\f'), new-line ('\n'), carriage return ('\r'),

+    horizontal tab ('\t'), and vertical tab ('\v'). In the "C" locale, isspace

+    returns true only for the standard white-space characters.

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int isspace(int c)

+int

+isspace(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CW)));

 }

 

-/**

+/** The isupper function tests for any character that is an uppercase letter or

+    is one of a locale-specific set of characters for which none of iscntrl,

+    isdigit, ispunct, or isspace is true. In the "C" locale, isupper returns

+    true only for the uppercase letters.

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int isupper(int c)

+int

+isupper(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CU)));

 }

 

-/**

+/** The isxdigit function tests for any hexadecimal-digit character.

 

-    @return

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

 **/

-int isxdigit(int c)

+int

+isxdigit(

+  IN  int c

+  )

 {

   return (__isCClass( c, (_CD | _CX)));

 }

 

-#if defined(_NETBSD_SOURCE)

+/** The isblank function tests that a character is a white-space character that results

+    in a number of space (' ') characters being sent to the output device.  In the C locale

+    this is either ' ' or '\t'.

+

+    @param[in]    c   The character to be tested.

+

+    @return   Returns nonzero (true) if and only if the value of the parameter c

+              can be classified as specified in the description of the function.

+**/

 int

-isblank(int c)

+isblank(

+  IN  int c

+  )

 {

   return (__isCClass( c, _CB));

 }

-#endif

 

-/** The isascii function tests that a character is one of the 128 ASCII characters.

+/** The isascii function tests that a character is one of the 128 7-bit ASCII characters.

 

   @param[in]  c   The character to test.

+

   @return     Returns nonzero (true) if c is a valid ASCII character.  Otherwize,

               zero (false) is returned.

 **/

-int isascii(int c){

+int

+isascii(

+  IN  int c

+  )

+{

   return ((c >= 0) && (c < 128));

 }

diff --git a/StdLib/LibC/Ctype/CConv.c b/StdLib/LibC/Ctype/CConv.c
index 6ad4f8722d..f551c43325 100644
--- a/StdLib/LibC/Ctype/CConv.c
+++ b/StdLib/LibC/Ctype/CConv.c
@@ -1,5 +1,5 @@
 /** @file

-  Case conversion functions for <ctype.h>

+  Case conversion function implementations for <ctype.h>

 

   The tolower function converts an uppercase letter to a corresponding

   lowercase letter.  If the argument is a character for which isupper

@@ -15,34 +15,56 @@
   of the corresponding characters (always the same one for any given locale);

   otherwise, the argument is returned unchanged.

 

-  Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>

+  Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>

   This program and the accompanying materials are licensed and made available under

   the terms and conditions of the BSD License that accompanies this distribution.

   The full text of the license may be found at

-  http://opensource.org/licenses/bsd-license.php.

+  http://opensource.org/licenses/bsd-license.

 

   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

-

 **/

 #include  <LibConfig.h>

 

 #define NO_CTYPE_MACROS            // So that we don't define the classification macros

 #include  <ctype.h>

 

+/** The tolower function converts an uppercase letter to a corresponding

+    lowercase letter.

+

+    @param[in]    c   The character to be converted.

+

+    @return   If the argument is a character for which isupper is true and

+              there are one or more corresponding characters, as specified by

+              the current locale, for which islower is true, the tolower

+              function returns one of the corresponding characters (always the

+              same one for any given locale); otherwise, the argument is

+              returned unchanged.

+**/

 int

 tolower(

-  int _c

+  IN  int _c

   )

 {

-//  return ((_c < 0 || _c > 127) ? _c : _lConvT[_c]);

   return (isupper(_c) ? _lConvT[_c] : _c);

 }

 

-int toupper(

-  int _c

+/** The toupper function converts a lowercase letter to a corresponding

+    uppercase letter.

+

+    @param[in]    c   The character to be converted.

+

+    @return   If the argument is a character for which islower is true and

+              there are one or more corresponding characters, as specified by

+              the current locale, for which isupper is true, the toupper

+              function returns one of the corresponding characters (always the

+              same one for any given locale); otherwise, the argument is

+              returned unchanged.

+**/

+int

+toupper(

+  IN  int _c

   )

 {

-//  return ((_c < 0 || _c > 127) ? _c : _uConvT[_c]);

   return (islower(_c) ? _uConvT[_c] : _c);

 }

diff --git a/StdLib/LibC/Ctype/iCtype.c b/StdLib/LibC/Ctype/iCtype.c
index 69df21e7ae..6b289bf2f2 100644
--- a/StdLib/LibC/Ctype/iCtype.c
+++ b/StdLib/LibC/Ctype/iCtype.c
@@ -4,20 +4,19 @@
 

   These are the default, C locale, tables.

 

-  Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>

+  Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>

   This program and the accompanying materials are licensed and made available under

   the terms and conditions of the BSD License that accompanies this distribution.

   The full text of the license may be found at

-  http://opensource.org/licenses/bsd-license.php.

+  http://opensource.org/licenses/bsd-license.

 

   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

-

 **/

 #include  <LibConfig.h>

 #include  <ctype.h>

 

-/// ASCII-8 Character Classification Table

+/// ASCII-7 Character Classification Table

 const UINT16  _C_CharClassTable[128] = {

   /* 00 NUL */    ( _CC ),

   /* 01 SOH */    ( _CC ),

@@ -149,7 +148,7 @@ const UINT16  _C_CharClassTable[128] = {
   /* 7F DEL */    ( _CC )

 };

 

-/// ASCII-8 Upper case to Lower case character conversion table

+/// ASCII-7 Upper case to Lower case character conversion table

 const UINT8  _C_ToLowerTable[128] = {

   /* 00 NUL */    0x00,           /* 01 SOH */    0x01,

   /* 02 STX */    0x02,           /* 03 ETX */    0x03,

@@ -217,7 +216,7 @@ const UINT8  _C_ToLowerTable[128] = {
   /* 7E '~' */    0x7E,           /* 7F DEL */    0x7F

 };

 

-/// ASCII-8 Lower case to Upper case character conversion table

+/// ASCII-7 Lower case to Upper case character conversion table

 const UINT8  _C_ToUpperTable[128] = {

   /* 00 NUL */    0x00,           /* 01 SOH */    0x01,

   /* 02 STX */    0x02,           /* 03 ETX */    0x03,

@@ -285,15 +284,21 @@ const UINT8  _C_ToUpperTable[128] = {
   /* 7E '~' */    0x7E,           /* 7F DEL */    0x7F

 };

 

-/// Default character classification table is 8-bit ASCII

+/// Default character classification table is 7-bit ASCII

 const UINT16  *_cClass = _C_CharClassTable;

 

-/// Default upper to lower conversion table is 8-bit ASCII

+/// Default upper to lower conversion table is 7-bit ASCII

 const UINT8  *_lConvT = _C_ToLowerTable;

 

-/// Default lower to upper conversion table is 8-bit ASCII

+/// Default lower to upper conversion table is 7-bit ASCII

 const UINT8  *_uConvT = _C_ToUpperTable;

 

+/** Sets the character classification and case conversion tables for the 'C' locale.

+

+    A set of locale-independent pointers are used to point to the classification and

+    conversion tables for the currently specified locale.  This function is used to

+    establish the tables for the 'C' locale.

+**/

 void

 __set_C_locale( void )

 {

diff --git a/StdLib/LibC/Main/assert.c b/StdLib/LibC/Main/assert.c
index a20a656ef0..a6b96d81d7 100644
--- a/StdLib/LibC/Main/assert.c
+++ b/StdLib/LibC/Main/assert.c
@@ -1,31 +1,57 @@
-/**

-  Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>

+/** @file

+  The implementation of the __assert function used internally by the assert macro

+  to insert diagnostic messages into code.

+

+  Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.<BR>

   This program and the accompanying materials are licensed and made available under

   the terms and conditions of the BSD License that accompanies this distribution.

   The full text of the license may be found at

-  http://opensource.org/licenses/bsd-license.php.

+  http://opensource.org/licenses/bsd-license.

 

   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,

   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.

 **/

-//#include  <Uefi.h>

-//#include  <Library/UefiLib.h>

-

 #include  <LibConfig.h>

 #include  <sys/EfiCdefs.h>

 

 #include  <stdio.h>

 #include  <stdlib.h>

 

+/** Internal helper function for the assert macro.

+    The __assert function prints a diagnostic message then exits the

+    currently running application.

+

+    This function should NEVER be called directly.

+

+    Some pre-processors do not provide the __func__ identifier.  When that is

+    the case, __func__ will be NULL.  This function accounts for this and

+    will modify the diagnostic message appropriately.

+

+

+    @param[in]    file          The name of the file containing the assert.

+    @param[in]    func          The name of the function containing the assert

+                                or NULL.

+    @param[in]    line          The line number the assert is located on.

+    @param[in]    failedexpr    A literal representation of the assert's expression.

+

+    @return       The __assert function will never return.  It terminates execution

+                  of the current application and returns to the environment that

+                  the application was launched from.

+**/

 void

-__assert(const char *func, const char *file, int line, const char *failedexpr)

+__assert(

+  IN  const char *file,

+  IN  const char *func,

+  IN  int         line,

+  IN  const char *failedexpr

+  )

 {

   if (func == NULL)

     printf("Assertion failed: (%s), file %s, line %d.\n",

                 failedexpr, file, line);

   else

-    printf("Assertion failed: (%s), function %s, file %s, line %d.\n",

-                failedexpr, func, file, line);

+    printf("Assertion failed: (%s), file %s, function %s, line %d.\n",

+                failedexpr, file, func, line);

   abort();

   /* NOTREACHED */

 }