From: darylm503 Date: Fri, 5 Aug 2011 23:02:43 +0000 (+0000) Subject: Update or add comments to files and functions for use by Doxygen. X-Git-Tag: edk2-stable201903~14433 X-Git-Url: https://git.proxmox.com/?p=mirror_edk2.git;a=commitdiff_plain;h=59d13433e7cbc810a6268d38141b0d1db353fa6e Update or add comments to files and functions for use by Doxygen. git-svn-id: https://edk2.svn.sourceforge.net/svnroot/edk2/trunk/edk2@12093 6f19259b-4bc3-4df7-8a09-765794883524 --- diff --git a/StdLib/Include/Ia32/machine/limits.h b/StdLib/Include/Ia32/machine/limits.h index 0b3cfbe4c5..f072e54a7d 100644 --- a/StdLib/Include/Ia32/machine/limits.h +++ b/StdLib/Include/Ia32/machine/limits.h @@ -1,14 +1,33 @@ +/** @file + This header defines several macros that expand to various + CPU-architecture-specific limits and parameters of the standard integer types. + + The values given below are constant expressions suitable for use + in #if preprocessing directives. + + Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.
+ 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. + + 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 +/** Number of bits making up a pointer. **/ #define __POINTER_BIT 32 + +/** Number of bits comprising an object of type long int. **/ #define __LONG_BIT 32 -/** minimum value for an object of type long int **/ -#define __LONG_MIN (-2147483647L - 1L) // -(2^31 - 1) +/** Minimum value for an object of type long int. **/ +#define __LONG_MIN (-2147483647L - 1L) // -(2^31 - 1) -/** maximum value for an object of type long int **/ -#define __LONG_MAX +2147483647L // 2^31 - 1 +/** Maximum value for an object of type long int. **/ +#define __LONG_MAX +2147483647L // 2^31 - 1 -/** maximum value for an object of type unsigned long int **/ -#define __ULONG_MAX 0xffffffff // 2^32 - 1 +/** Maximum value for an object of type unsigned long int. **/ +#define __ULONG_MAX 0xffffffff // 2^32 - 1 diff --git a/StdLib/Include/iso646.h b/StdLib/Include/iso646.h index db3450193d..d9dc860346 100644 --- a/StdLib/Include/iso646.h +++ b/StdLib/Include/iso646.h @@ -17,16 +17,16 @@ #define _ISO646_H #include -#define and && -#define and_eq &= -#define bitand & -#define bitor | -#define compl ~ -#define not ! -#define not_eq != -#define or || -#define or_eq |= -#define xor ^ -#define xor_eq ^= +#define and && ///< Logical AND of two boolean expressions +#define and_eq &= ///< Bitwise AND with assignment to lval +#define bitand & ///< Bitwise AND of two scalar expressions +#define bitor | ///< Bitwise OR of two scalar expressions +#define compl ~ ///< Binary complement +#define not ! ///< Logical complement of a boolean expression +#define not_eq != ///< Not-equal comparison +#define or || ///< Logical OR of two boolean expressions +#define or_eq |= ///< Bitwise OR with assignment to lval +#define xor ^ ///< Exclusive OR +#define xor_eq ^= ///< Exclusive OR with assignment to lval #endif /* _ISO646_H */ diff --git a/StdLib/Include/limits.h b/StdLib/Include/limits.h index c0e60fe007..4fceca2015 100644 --- a/StdLib/Include/limits.h +++ b/StdLib/Include/limits.h @@ -2,30 +2,20 @@ The header defines several macros that expand to various limits and parameters of the standard integer types. - The values given below shall be replaced by constant expressions suitable for - use in #if preprocessing directives. Moreover, except for CHAR_BIT and - MB_LEN_MAX, the following shall be replaced by expressions that have the same + The values given below are constant expressions suitable for + use in #if preprocessing directives. Except for CHAR_BIT and + MB_LEN_MAX, they have the same type as would an expression that is an object of the corresponding type - converted according to the integer promotions. Their implementation-defined - values shall be equal or greater in magnitude (absolute value) to those - documented, with the same sign. - - If the value of an object of type char is treated as a signed integer when - used in an expression, the value of CHAR_MIN shall be the same as that of - SCHAR_MIN and the value of CHAR_MAX shall be the same as that of SCHAR_MAX. - Otherwise, the value of CHAR_MIN shall be 0 and the value of CHAR_MAX shall - be the same as that of UCHAR_MAX.) - The value UCHAR_MAX shall equal 2^(CHAR_BIT - 1). - - Copyright (c) 2010, Intel Corporation. All rights reserved.
+ converted according to the integer promotions. + + Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.
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. - **/ #ifndef _LIMITS_H #define _LIMITS_H @@ -35,86 +25,91 @@ /* Get the architecturally defined limits for this compilation unit. */ #include -/* Define the values required by Specification. */ +/* Define the values required by the ISO/IEC 9899 Specification. */ -/** maximum number of bytes in a multibyte character, for any supported locale **/ -#define MB_LEN_MAX 2 /* 16-bit UTC-2 */ +/** Maximum number of bytes in a multibyte character, for any supported locale. **/ +#define MB_LEN_MAX 2 /* 16-bit UTC-2 */ -/** Number of bits for smallest object that is not a bit-field (byte). **/ +/** Number of bits comprising the smallest object that is not a bit-field (byte). **/ #define CHAR_BIT __CHAR_BIT -/** minimum value for an object of type signed char **/ +/** Minimum value for an object of type signed char. **/ #define SCHAR_MIN __SCHAR_MIN -/** maximum value for an object of type signed char **/ +/** Maximum value for an object of type signed char. **/ #define SCHAR_MAX __SCHAR_MAX -/** maximum value for an object of type unsigned char **/ +/** Maximum value for an object of type unsigned char. **/ #define UCHAR_MAX __UCHAR_MAX #ifdef __CHAR_UNSIGNED__ - /** maximum value for an object of type char **/ + /** Maximum value for an object of type char. **/ #define CHAR_MAX UCHAR_MAX - /** minimum value for an object of type char **/ + /** Minimum value for an object of type char. **/ #define CHAR_MIN 0 #else - /** maximum value for an object of type char **/ + /** Maximum value for an object of type char. **/ #define CHAR_MAX SCHAR_MAX - /** minimum value for an object of type char **/ + /** Minimum value for an object of type char. **/ #define CHAR_MIN SCHAR_MIN #endif -/** minimum value for an object of type short int **/ +/** Minimum value for an object of type short int. **/ #define SHRT_MIN __SHRT_MIN -/** maximum value for an object of type short int **/ +/** Maximum value for an object of type short int. **/ #define SHRT_MAX __SHRT_MAX -/** maximum value for an object of type unsigned short int **/ +/** Maximum value for an object of type unsigned short int. **/ #define USHRT_MAX __USHRT_MAX -/** minimum value for an object of type int **/ +/** Minimum value for an object of type int. **/ #define INT_MIN __INT_MIN -/** maximum value for an object of type int **/ +/** Maximum value for an object of type int. **/ #define INT_MAX __INT_MAX -/** maximum value for an object of type unsigned int **/ +/** Maximum value for an object of type unsigned int. **/ #define UINT_MAX __UINT_MAX -/** minimum value for an object of type long int **/ +/** Minimum value for an object of type long int. **/ #define LONG_MIN __LONG_MIN -/** maximum value for an object of type long int **/ +/** Maximum value for an object of type long int. **/ #define LONG_MAX __LONG_MAX -/** maximum value for an object of type unsigned long int **/ +/** Maximum value for an object of type unsigned long int. **/ #define ULONG_MAX __ULONG_MAX -/** minimum value for an object of type long long int **/ +/** Minimum value for an object of type long long int. **/ #define LLONG_MIN __LLONG_MIN -/** maximum value for an object of type long long int **/ +/** Maximum value for an object of type long long int. **/ #define LLONG_MAX __LLONG_MAX -/** maximum value for an object of type unsigned long long int **/ +/** Maximum value for an object of type unsigned long long int. **/ #define ULLONG_MAX __ULLONG_MAX /* Object limits used in the Standard Libraries */ #if (PcdGet32(PcdMaximumAsciiStringLength) > 0) + /** Maximum length of an arbitrary "narrow-character" string. **/ #define ASCII_STRING_MAX PcdGet32(PcdMaximumAsciiStringLength) #else + /** Maximum length of an arbitrary "narrow-character" string. **/ #define ASCII_STRING_MAX 256 #endif #if (PcdGet32(PcdMaximumUnicodeStringLength) > 0) + /** Maximum length of an arbitrary "wide-character" string. **/ #define UNICODE_STRING_MAX PcdGet32(PcdMaximumUnicodeStringLength) #else + /** Maximum length of an arbitrary "wide-character" string. **/ #define UNICODE_STRING_MAX 512 #endif /* Limits for BSD Compatibility */ #define NL_TEXTMAX 2048 + #include #endif /* _LIMITS_H */ diff --git a/StdLib/Include/locale.h b/StdLib/Include/locale.h index 220f35a043..73a6bf4ca7 100644 --- a/StdLib/Include/locale.h +++ b/StdLib/Include/locale.h @@ -1,6 +1,15 @@ -/* $NetBSD: locale.h,v 1.14 2005/02/03 04:39:32 perry Exp $ */ +/** @file + Localization functions and macros. + + Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.
+ 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. + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -/* * Copyright (c) 1991, 1993 * The Regents of the University of California. All rights reserved. * @@ -29,11 +38,15 @@ * SUCH DAMAGE. * * @(#)locale.h 8.1 (Berkeley) 6/2/93 - */ + * $NetBSD: locale.h,v 1.14 2005/02/03 04:39:32 perry Exp +**/ #ifndef _LOCALE_H_ #define _LOCALE_H_ +/** This is a structure containing members pertaining to the formatting of numeric values. + There is no requirement for members of this structure to be in any particular order. +**/ struct lconv { char *decimal_point; char *thousands_sep; @@ -61,27 +74,42 @@ struct lconv { char int_n_sign_posn; }; -#define LC_ALL 0 -#define LC_COLLATE 1 -#define LC_CTYPE 2 -#define LC_MONETARY 3 -#define LC_NUMERIC 4 -#define LC_TIME 5 -#define LC_MESSAGES 6 +/** These macros expand to integer expressions suitable for use as the first + argument to the setlocale() function. -#define _LC_LAST 7 /* marks end */ + Only the first six macros are required by the C language specification. + Implementations are free to extend this list, as has been done with LC_MESSAGES, + with additional macro definitions, beginning with the characters LC_ and + an uppercase letter. +@{ +**/ +#define LC_ALL 0 ///< The application's entire locale. +#define LC_COLLATE 1 ///< Affects the behavior of the strcoll and strxfrm functions. +#define LC_CTYPE 2 ///< Affects the behavior of the character handling, multibyte, and wide character functions. +#define LC_MONETARY 3 ///< Affects monetary formatting information. +#define LC_NUMERIC 4 ///< Affects the decimal-point character and non-monetary formatting information. +#define LC_TIME 5 ///< Affects the behavior of the strftime and wcsftime functions. +#define LC_MESSAGES 6 +#define _LC_LAST 7 ///< Number of defined macros. Marks end. +/// @} #include +/** @fn char *setlocale(int, const char *) +**/ + +/** @fn struct lconv *localeconv(void) +**/ + __BEGIN_DECLS -struct lconv *localeconv(void); - char *__setlocale_mb_len_max_32(int, const char *); #ifdef __SETLOCALE_SOURCE__ char *setlocale(int, const char *); char *__setlocale(int, const char *); #else /* !__SETLOCALE_SOURCE__ */ char *setlocale(int, const char *) __RENAME(__setlocale_mb_len_max_32); #endif /* !__SETLOCALE_SOURCE__ */ +struct lconv *localeconv(void); + char *__setlocale_mb_len_max_32(int, const char *); __END_DECLS #endif /* _LOCALE_H_ */ diff --git a/StdLib/Include/sys/syslimits.h b/StdLib/Include/sys/syslimits.h index d308387f2a..bee810cc12 100644 --- a/StdLib/Include/sys/syslimits.h +++ b/StdLib/Include/sys/syslimits.h @@ -1,6 +1,15 @@ -/* $NetBSD: syslimits.h,v 1.23 2005/12/11 12:25:21 christos Exp $ */ +/** @file + Platform specific values for . + + Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.
+ 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. + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -/* * Copyright (c) 1988, 1993 * The Regents of the University of California. All rights reserved. * @@ -28,28 +37,30 @@ * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. * - * @(#)syslimits.h 8.1 (Berkeley) 6/2/93 - */ + * syslimits.h 8.1 (Berkeley) 6/2/93 + * NetBSD: syslimits.h,v 1.23 2005/12/11 12:25:21 christos Exp +**/ #ifndef _SYS_SYSLIMITS_H_ #define _SYS_SYSLIMITS_H_ #include -#define ARG_MAX (2 * 1024) /* max bytes for an exec function */ -#define ARGC_MAX (64) /* Maximum value for argc */ +#define ARG_MAX (2 * 1024) ///< Maximum bytes for an exec function. +#define ARGC_MAX (64) ///< Maximum value for argc. -#ifndef CHILD_MAX - #define CHILD_MAX 128 /* max simultaneous processes */ -#endif -#define MAX_INPUT 255 /* max bytes in terminal input */ -#define NAME_MAX 255 /* max bytes in a file name */ +#define MAX_INPUT 255 ///< Maximum bytes in terminal input. +#define NAME_MAX 255 ///< Maximum bytes in a file name. #ifndef OPEN_MAX - #define OPEN_MAX 20 /* max open files per process */ + #define OPEN_MAX 20 ///< Maximum open files per process. +#endif +#define PATH_MAX 1024 ///< Maximum bytes in pathname. +#define PIPE_BUF 512 ///< Maximum bytes for atomic pipe writes. + +#ifndef CHILD_MAX + #define CHILD_MAX 128 ///< Maximum simultaneous processes. #endif -#define PATH_MAX 1024 /* max bytes in pathname */ -#define PIPE_BUF 512 /* max bytes for atomic pipe writes */ -#define LOGIN_NAME_MAX 17 /* max login name length incl. NUL */ +#define LOGIN_NAME_MAX 17 ///< Maximum login name length including the NUL. #endif /* !_SYS_SYSLIMITS_H_ */ diff --git a/StdLib/Include/x86/limits.h b/StdLib/Include/x86/limits.h index 08222fa2d6..b5339c2fdc 100644 --- a/StdLib/Include/x86/limits.h +++ b/StdLib/Include/x86/limits.h @@ -1,14 +1,14 @@ /** @file - Machine specific values for . + Intel x86 architecture (both Ia32 and X64) specific values for . Within this file, the ^ character is used in comments to represent exponentiation. Thus, 2^7 means "2 to the 7th power", NOT "2 XOR 7". - Copyright (c) 2010, Intel Corporation. All rights reserved.
+ Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.
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. @@ -19,49 +19,49 @@ /** Number of bits for smallest object that is not a bit-field (byte). **/ #define __CHAR_BIT 8 -/** minimum value for an object of type signed char **/ +/** Minimum value for an object of type signed char. **/ #define __SCHAR_MIN -128 // -(2^7 - 1) -/** maximum value for an object of type signed char **/ +/** Maximum value for an object of type signed char. **/ #define __SCHAR_MAX +127 // 2^7 - 1 -/** maximum value for an object of type unsigned char **/ +/** Maximum value for an object of type unsigned char. **/ #define __UCHAR_MAX 255 // 2^8 - 1 -/** minimum value for an object of type short int **/ +/** Minimum value for an object of type short int. **/ #define __SHRT_MIN -32768 // -(2^15 - 1) -/** maximum value for an object of type short int **/ +/** Maximum value for an object of type short int. **/ #define __SHRT_MAX +32767 // 2^15 - 1 -/** maximum value for an object of type unsigned short int **/ +/** Maximum value for an object of type unsigned short int. **/ #define __USHRT_MAX 65535 // 2^16 - 1 -/** maximum value for an object of type int **/ +/** Maximum value for an object of type int. **/ #define __INT_MAX +2147483647 // 2^31 - 1 -/** minimum value for an object of type int **/ +/** Minimum value for an object of type int. **/ #define __INT_MIN (-2147483647 - 1) // -(2^31 - 1) -/** maximum value for an object of type unsigned int **/ +/** Maximum value for an object of type unsigned int. **/ #define __UINT_MAX 0xffffffff // 2^32 - 1 -/** minimum value for an object of type long long int **/ -//#define __LLONG_MIN -9223372036854775808LL // -(2^63 - 1) -//#define __LLONG_MIN ((-9223372036854775807LL)-1) // -(2^63 - 1) -#define __LLONG_MIN (-9223372036854775807LL - 1LL) // -(2^63 - 1) +/** Minimum value for an object of type long long int. **/ +#define __LLONG_MIN (-9223372036854775807LL - 1LL) // -(2^63 - 1) -/** maximum value for an object of type long long int **/ +/** Maximum value for an object of type long long int. **/ #define __LLONG_MAX 9223372036854775807LL // 2^63 - 1 -/** maximum value for an object of type unsigned long long int **/ -//#define __ULLONG_MAX 18446744073709551615ULL // 2^64 - 1 +/** Maximum value for an object of type unsigned long long int. **/ #define __ULLONG_MAX 0xFFFFFFFFFFFFFFFFULL // 2^64 - 1 -/* Intel extensions to for UEFI */ -#define __SHORT_BIT 16 -#define __WCHAR_BIT 16 -#define __INT_BIT 32 -#define __LONG_LONG_BIT 64 +/** Intel extensions to for UEFI +@{ +**/ +#define __SHORT_BIT 16 ///< Number of bits comprising a short int. +#define __WCHAR_BIT 16 ///< Number of bits comprising a wide character. +#define __INT_BIT 32 ///< Number of bits comprising an int. +#define __LONG_LONG_BIT 64 ///< Number of bits comprising a long long int. +/// @} #endif /* _MACHINE_LIMITS_H */ diff --git a/StdLib/LibC/Locale/setlocale.c b/StdLib/LibC/Locale/setlocale.c index b6090d2ea0..4d617d21da 100644 --- a/StdLib/LibC/Locale/setlocale.c +++ b/StdLib/LibC/Locale/setlocale.c @@ -1,6 +1,15 @@ -/* $NetBSD: setlocale.c,v 1.50 2006/02/16 19:19:49 tnozaki Exp $ */ +/** @file + Worker functions for the setlocale function. + + Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.
+ 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. + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -/* * Copyright (c) 1991, 1993 * The Regents of the University of California. All rights reserved. * @@ -30,16 +39,12 @@ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. - */ + + setlocale.c 8.1 (Berkeley) 7/4/93 + * NetBSD: setlocale.c,v 1.50 2006/02/16 19:19:49 tnozaki Exp +**/ #include #include -#if defined(LIBC_SCCS) && !defined(lint) - #if 0 - static char sccsid[] = "@(#)setlocale.c 8.1 (Berkeley) 7/4/93"; - #else - __RCSID("$NetBSD: setlocale.c,v 1.50 2006/02/16 19:19:49 tnozaki Exp $"); - #endif -#endif /* LIBC_SCCS and not lint */ #if defined(_MSC_VER) // Disable warnings about assignment within conditional expressions. @@ -86,9 +91,7 @@ const char *_PathLocale = NULL; #endif -/* - * Category names for getenv() - */ +/** Category names for getenv(). **/ static const char *const categories[_LC_LAST] = { "LC_ALL", "LC_COLLATE", @@ -99,9 +102,7 @@ static const char *const categories[_LC_LAST] = { "LC_MESSAGES" }; -/* - * Current locales for each category - */ +/** Current locales for each category. **/ static char current_categories[_LC_LAST][32] = { "C", "C", diff --git a/StdLib/LibC/Locale/setlocale1.c b/StdLib/LibC/Locale/setlocale1.c index b9c30bb40d..e315ec8ab0 100644 --- a/StdLib/LibC/Locale/setlocale1.c +++ b/StdLib/LibC/Locale/setlocale1.c @@ -1,6 +1,15 @@ -/* $NetBSD: setlocale1.c,v 1.2 2003/03/11 17:23:07 tshiozak Exp $ */ +/** @file + Single-byte character version of the setlocale function. + + Copyright (c) 2010 - 2011, Intel Corporation. All rights reserved.
+ 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. + + THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, + WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. -/*- * Copyright (c)1999 Citrus Project, * All rights reserved. * @@ -24,12 +33,11 @@ * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. - */ + + * NetBSD: setlocale1.c,v 1.2 2003/03/11 17:23:07 tshiozak Exp +**/ #include #include -#if defined(LIBC_SCCS) && !defined(lint) -__RCSID("$NetBSD: setlocale1.c,v 1.2 2003/03/11 17:23:07 tshiozak Exp $"); -#endif /* LIBC_SCCS and not lint */ #include "namespace.h" #define __SETLOCALE_SOURCE__