Reviewed-by: Eric Dong <eric.d...@intel.com> -----Original Message----- From: Bi, Dandan Sent: Friday, September 11, 2015 2:29 PM To: Dong, Eric; Qiu, Shumin; edk2-devel@lists.01.org Subject: [patch] MdeModulePkg:Refine the code comments in RegularExpressionDxe.
Contributed-under: TianoCore Contribution Agreement 1.0 Signed-off-by: Dandan Bi <dandan...@intel.com> --- .../RegularExpressionDxe/RegularExpressionDxe.c | 146 +++++++++++++-------- .../RegularExpressionDxe/RegularExpressionDxe.h | 108 +++++++-------- .../RegularExpressionDxe/RegularExpressionDxe.inf | 10 +- 3 files changed, 151 insertions(+), 113 deletions(-) diff --git a/MdeModulePkg/Universal/RegularExpressionDxe/RegularExpressionDxe.c b/MdeModulePkg/Universal/RegularExpressionDxe/RegularExpressionDxe.c index 6c62957..a341a2b 100644 --- a/MdeModulePkg/Universal/RegularExpressionDxe/RegularExpressionDxe.c +++ b/MdeModulePkg/Universal/RegularExpressionDxe/RegularExpressionDxe.c @@ -1,7 +1,6 @@ -/** - @file +/** @file EFI_REGULAR_EXPRESSION_PROTOCOL Implementation Copyright (c) 2015, Hewlett Packard Enterprise Development, L.P.<BR> @@ -10,10 +9,11 @@ distribution. The full text of the license may be found at http://opensource.org/licenses/bsd-license.php. 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 "RegularExpressionDxe.h" STATIC @@ -34,13 +34,45 @@ EFI_REGULAR_EXPRESSION_PROTOCOL mProtocolInstance = { /** Call the Oniguruma regex match API. Same parameters as RegularExpressionMatch, except SyntaxType is required. + + @param String A pointer to a NULL terminated string to match against the + regular expression string specified by Pattern. + + @param Pattern A pointer to a NULL terminated string that represents the + regular expression. + @param SyntaxType A pointer to the EFI_REGEX_SYNTAX_TYPE that identifies the + regular expression syntax type to use. May be NULL in which + case the function will use its default regular expression + syntax type. + + @param Result On return, points to TRUE if String fully matches against + the regular expression Pattern using the regular expression + SyntaxType. Otherwise, points to FALSE. + + @param Captures A Pointer to an array of EFI_REGEX_CAPTURE objects to receive + the captured groups in the event of a match. The full + sub-string match is put in Captures[0], and the results of N + capturing groups are put in Captures[1:N]. If Captures is + NULL, then this function doesn't allocate the memory for the + array and does not build up the elements. It only returns the + number of matching patterns in CapturesCount. If Captures is + not NULL, this function returns a pointer to an array and + builds up the elements in the array. CapturesCount is also + updated to the number of matching patterns found. It is the + caller's responsibility to free the memory pool in Captures + and in each CapturePtr in the array elements. + + @param CapturesCount On output, CapturesCount is the number of matching patterns + found in String. Zero means no matching patterns were found + in the string. + + @retval EFI_SUCCESS Regex compilation and match completed successfully. + @retval EFI_DEVICE_ERROR Regex compilation failed. - @retval EFI_SUCCESS Regex compilation and match completed successfully. - @retval EFI_DEVICE_ERROR Regex compilation failed. **/ STATIC EFI_STATUS OnigurumaMatch ( IN CHAR16 *String, @@ -142,27 +174,27 @@ OnigurumaMatch ( /** Returns information about the regular expression syntax types supported by the implementation. - This A pointer to the EFI_REGULAR_EXPRESSION_PROTOCOL - instance. + @param This A pointer to the EFI_REGULAR_EXPRESSION_PROTOCOL + instance. - RegExSyntaxTypeListSize On input, the size in bytes of RegExSyntaxTypeList. - On output with a return code of EFI_SUCCESS, the - size in bytes of the data returned in - RegExSyntaxTypeList. On output with a return code - of EFI_BUFFER_TOO_SMALL, the size of - RegExSyntaxTypeList required to obtain the list. + @param RegExSyntaxTypeListSize On input, the size in bytes of RegExSyntaxTypeList. + On output with a return code of EFI_SUCCESS, the + size in bytes of the data returned in + RegExSyntaxTypeList. On output with a return code + of EFI_BUFFER_TOO_SMALL, the size of + RegExSyntaxTypeList required to obtain the list. - RegExSyntaxTypeList A caller-allocated memory buffer filled by the - driver with one EFI_REGEX_SYNTAX_TYPE element - for each supported Regular expression syntax - type. The list must not change across multiple - calls to the same driver. The first syntax - type in the list is the default type for the - driver. + @param RegExSyntaxTypeList A caller-allocated memory buffer filled by the + driver with one EFI_REGEX_SYNTAX_TYPE element + for each supported Regular expression syntax + type. The list must not change across multiple + calls to the same driver. The first syntax + type in the list is the default type for the + driver. @retval EFI_SUCCESS The regular expression syntax types list was returned successfully. @retval EFI_UNSUPPORTED The service is not supported by this driver. @retval EFI_DEVICE_ERROR The list of syntax types could not be @@ -207,45 +239,45 @@ RegularExpressionGetInfo ( } /** Checks if the input string matches to the regular expression pattern. - This A pointer to the EFI_REGULAR_EXPRESSION_PROTOCOL instance. - Type EFI_REGULAR_EXPRESSION_PROTOCOL is defined in Section - XYZ. - - String A pointer to a NULL terminated string to match against the - regular expression string specified by Pattern. - - Pattern A pointer to a NULL terminated string that represents the - regular expression. - - SyntaxType A pointer to the EFI_REGEX_SYNTAX_TYPE that identifies the - regular expression syntax type to use. May be NULL in which - case the function will use its default regular expression - syntax type. - - Result On return, points to TRUE if String fully matches against - the regular expression Pattern using the regular expression - SyntaxType. Otherwise, points to FALSE. - - Captures A Pointer to an array of EFI_REGEX_CAPTURE objects to receive - the captured groups in the event of a match. The full - sub-string match is put in Captures[0], and the results of N - capturing groups are put in Captures[1:N]. If Captures is - NULL, then this function doesn't allocate the memory for the - array and does not build up the elements. It only returns the - number of matching patterns in CapturesCount. If Captures is - not NULL, this function returns a pointer to an array and - builds up the elements in the array. CapturesCount is also - updated to the number of matching patterns found. It is the - caller's responsibility to free the memory pool in Captures - and in each CapturePtr in the array elements. - - CapturesCount On output, CapturesCount is the number of matching patterns - found in String. Zero means no matching patterns were found - in the string. + @param This A pointer to the EFI_REGULAR_EXPRESSION_PROTOCOL instance. + Type EFI_REGULAR_EXPRESSION_PROTOCOL is defined in Section + XYZ. + + @param String A pointer to a NULL terminated string to match against the + regular expression string specified by Pattern. + + @param Pattern A pointer to a NULL terminated string that represents the + regular expression. + + @param SyntaxType A pointer to the EFI_REGEX_SYNTAX_TYPE that identifies the + regular expression syntax type to use. May be NULL in which + case the function will use its default regular expression + syntax type. + + @param Result On return, points to TRUE if String fully matches against + the regular expression Pattern using the regular expression + SyntaxType. Otherwise, points to FALSE. + + @param Captures A Pointer to an array of EFI_REGEX_CAPTURE objects to receive + the captured groups in the event of a match. The full + sub-string match is put in Captures[0], and the results of N + capturing groups are put in Captures[1:N]. If Captures is + NULL, then this function doesn't allocate the memory for the + array and does not build up the elements. It only returns the + number of matching patterns in CapturesCount. If Captures is + not NULL, this function returns a pointer to an array and + builds up the elements in the array. CapturesCount is also + updated to the number of matching patterns found. It is the + caller's responsibility to free the memory pool in Captures + and in each CapturePtr in the array elements. + + @param CapturesCount On output, CapturesCount is the number of matching patterns + found in String. Zero means no matching patterns were found + in the string. @retval EFI_SUCCESS The regular expression string matching completed successfully. @retval EFI_UNSUPPORTED The regular expression syntax specified by SyntaxType is not supported by this driver. @@ -298,10 +330,16 @@ RegularExpressionMatch ( return Status; } /** Entry point for RegularExpressionDxe. + + @param ImageHandle Image handle this driver. + @param SystemTable Pointer to SystemTable. + + @retval Status Whether this function complete successfully. + **/ EFI_STATUS EFIAPI RegularExpressionDxeEntry ( IN EFI_HANDLE ImageHandle, diff --git a/MdeModulePkg/Universal/RegularExpressionDxe/RegularExpressionDxe.h b/MdeModulePkg/Universal/RegularExpressionDxe/RegularExpressionDxe.h index 4673471..014a208 100644 --- a/MdeModulePkg/Universal/RegularExpressionDxe/RegularExpressionDxe.h +++ b/MdeModulePkg/Universal/RegularExpressionDxe/RegularExpressionDxe.h @@ -1,8 +1,6 @@ -/** - @file - +/** @file EFI_REGULAR_EXPRESSION_PROTOCOL Header File. Copyright (c) 2015, Hewlett Packard Enterprise Development, L.P.<BR> This program and the accompanying materials are licensed and made available @@ -10,12 +8,16 @@ distribution. The full text of the license may be found at http://opensource.org/licenses/bsd-license.php. 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 __REGULAR_EXPRESSIONDXE_H__ +#define __REGULAR_EXPRESSIONDXE_H__ + #include "Oniguruma/oniguruma.h" #include <Uefi.h> #include <Protocol/RegularExpressionProtocol.h> #include <Library/UefiBootServicesTableLib.h> @@ -27,43 +29,43 @@ #define ARRAY_SIZE(Array) (sizeof(Array) / sizeof(*Array)) /** Checks if the input string matches to the regular expression pattern. - This A pointer to the EFI_REGULAR_EXPRESSION_PROTOCOL instance. - Type EFI_REGULAR_EXPRESSION_PROTOCOL is defined in Section - XYZ. - - String A pointer to a NULL terminated string to match against the - regular expression string specified by Pattern. - - Pattern A pointer to a NULL terminated string that represents the - regular expression. - - SyntaxType A pointer to the EFI_REGEX_SYNTAX_TYPE that identifies the - regular expression syntax type to use. May be NULL in which - case the function will use its default regular expression - syntax type. - - Result On return, points to TRUE if String fully matches against - the regular expression Pattern using the regular expression - SyntaxType. Otherwise, points to FALSE. - - Captures A Pointer to an array of EFI_REGEX_CAPTURE objects to receive - the captured groups in the event of a match. The full - sub-string match is put in Captures[0], and the results of N - capturing groups are put in Captures[1:N]. If Captures is - NULL, then this function doesn't allocate the memory for the - array and does not build up the elements. It only returns the - number of matching patterns in CapturesCount. If Captures is - not NULL, this function returns a pointer to an array and - builds up the elements in the array. CapturesCount is also - updated to the number of matching patterns found. It is the - caller's responsibility to free the memory pool in Captures - and in each CapturePtr in the array elements. - - CapturesCount On output, CapturesCount is the number of matching patterns + @param This A pointer to the EFI_REGULAR_EXPRESSION_PROTOCOL instance. + Type EFI_REGULAR_EXPRESSION_PROTOCOL is defined in Section + XYZ. + + @param String A pointer to a NULL terminated string to match against the + regular expression string specified by Pattern. + + @param Pattern A pointer to a NULL terminated string that represents the + regular expression. + + @param SyntaxType A pointer to the EFI_REGEX_SYNTAX_TYPE that identifies the + regular expression syntax type to use. May be NULL in which + case the function will use its default regular expression + syntax type. + + @param Result On return, points to TRUE if String fully matches against + the regular expression Pattern using the regular expression + SyntaxType. Otherwise, points to FALSE. + + @param Captures A Pointer to an array of EFI_REGEX_CAPTURE objects to receive + the captured groups in the event of a match. The full + sub-string match is put in Captures[0], and the results of N + capturing groups are put in Captures[1:N]. If Captures is + NULL, then this function doesn't allocate the memory for the + array and does not build up the elements. It only returns the + number of matching patterns in CapturesCount. If Captures is + not NULL, this function returns a pointer to an array and + builds up the elements in the array. CapturesCount is also + updated to the number of matching patterns found. It is the + caller's responsibility to free the memory pool in Captures + and in each CapturePtr in the array elements. + + @param CapturesCount On output, CapturesCount is the number of + matching patterns found in String. Zero means no matching patterns were found in the string. @retval EFI_SUCCESS The regular expression string matching completed successfully. @@ -89,27 +91,27 @@ RegularExpressionMatch ( /** Returns information about the regular expression syntax types supported by the implementation. - This A pointer to the EFI_REGULAR_EXPRESSION_PROTOCOL - instance. - - RegExSyntaxTypeListSize On input, the size in bytes of RegExSyntaxTypeList. - On output with a return code of EFI_SUCCESS, the - size in bytes of the data returned in - RegExSyntaxTypeList. On output with a return code - of EFI_BUFFER_TOO_SMALL, the size of - RegExSyntaxTypeList required to obtain the list. - - RegExSyntaxTypeList A caller-allocated memory buffer filled by the - driver with one EFI_REGEX_SYNTAX_TYPE element - for each supported Regular expression syntax - type. The list must not change across multiple - calls to the same driver. The first syntax - type in the list is the default type for the - driver. + @param This A pointer to the EFI_REGULAR_EXPRESSION_PROTOCOL + instance. + + @param RegExSyntaxTypeListSize On input, the size in bytes of RegExSyntaxTypeList. + On output with a return code of EFI_SUCCESS, the + size in bytes of the data returned in + RegExSyntaxTypeList. On output with a return code + of EFI_BUFFER_TOO_SMALL, the size of + RegExSyntaxTypeList required to obtain the list. + + @param RegExSyntaxTypeList A caller-allocated memory buffer filled by the + driver with one EFI_REGEX_SYNTAX_TYPE element + for each supported Regular expression syntax + type. The list must not change across multiple + calls to the same driver. The first syntax + type in the list is the default type for the + driver. @retval EFI_SUCCESS The regular expression syntax types list was returned successfully. @retval EFI_UNSUPPORTED The service is not supported by this driver. @retval EFI_DEVICE_ERROR The list of syntax types could not be diff --git a/MdeModulePkg/Universal/RegularExpressionDxe/RegularExpressionDxe.inf b/MdeModulePkg/Universal/RegularExpressionDxe/RegularExpressionDxe.inf index 7f1023e..36458fa 100644 --- a/MdeModulePkg/Universal/RegularExpressionDxe/RegularExpressionDxe.inf +++ b/MdeModulePkg/Universal/RegularExpressionDxe/RegularExpressionDxe.i +++ nf @@ -1,8 +1,6 @@ -## -# @file -# +## @file # EFI_REGULAR_EXPRESSION_PROTOCOL Implementation # # Copyright (c) 2015, Hewlett Packard Enterprise Development, L.P.<BR> # # This program and the accompanying materials are licensed and made available @@ -65,15 +63,15 @@ MemoryAllocationLib BaseMemoryLib DebugLib [Guids] - gEfiRegexSyntaxTypePosixExtendedGuid - gEfiRegexSyntaxTypePerlGuid + gEfiRegexSyntaxTypePosixExtendedGuid ## CONSUMES ## GUID + gEfiRegexSyntaxTypePerlGuid ## CONSUMES ## GUID [Protocols] - gEfiRegularExpressionProtocolGuid + gEfiRegularExpressionProtocolGuid ## PRODUCES [BuildOptions] # Override MSFT build option to remove /Oi and /GL MSFT:DEBUG_*_IA32_CC_FLAGS == /nologo /c /WX /GS- /W4 /Gs32768 /D UNICODE /O1b2 /FIAutoGen.h /EHs-c- /GR- /GF /Gy /Zi /Gm MSFT:RELEASE_*_IA32_CC_FLAGS == /nologo /c /WX /GS- /W4 /Gs32768 /D UNICODE /O1b2 /FIAutoGen.h /EHs-c- /GR- /GF -- 1.9.5.msysgit.1 _______________________________________________ edk2-devel mailing list edk2-devel@lists.01.org https://lists.01.org/mailman/listinfo/edk2-devel
