BaseTools: Source/C/Common: Fix doc block locations and convert to Doxygen

Move the documentation blocks from between the parameter list and function
body to above the function.

Convert all the documentation blocks to Doxygen format.

Signed-off-by: Rebecca Cran <rebecca@bsdio.com>
Reviewed-by: Liming Gao <gaoliming@byosoft.com.cn>

1 files changed, 50 insertions, 96 deletions

diff --git a/BaseTools/Source/C/Common/MyAlloc.h b/BaseTools/Source/C/Common/MyAlloc.h
index aff29d0..de3323d 100644
--- a/BaseTools/Source/C/Common/MyAlloc.h
+++ b/BaseTools/Source/C/Common/MyAlloc.h
@@ -71,6 +71,17 @@ typedef struct MyAllocStruct {
 #define MYALLOC_HEAD_MAGIK  0xBADFACED

 #define MYALLOC_TAIL_MAGIK  0xDEADBEEF

 

+/**

+  Check for corruptions in the allocated memory chain.  If a corruption

+  is detection program operation stops w/ an exit(1) call.

+

+  @param Final When FALSE, MyCheck() returns if the allocated memory chain

+               has not been corrupted.  When TRUE, MyCheck() returns if there

+               are no un-freed allocations.  If there are un-freed allocations,

+               they are displayed and exit(1) is called.

+  @param File Set to __FILE__ by macro expansion.

+  @param Line Set to __LINE__ by macro expansion.

+**/

 VOID

 MyCheck (

   BOOLEAN      Final,

@@ -78,31 +89,20 @@ MyCheck (
   UINTN        Line

   )

 ;

-//

-// *++

-// Description:

-//

-//  Check for corruptions in the allocated memory chain.  If a corruption

-//  is detection program operation stops w/ an exit(1) call.

-//

-// Parameters:

-//

-//  Final := When FALSE, MyCheck() returns if the allocated memory chain

-//           has not been corrupted.  When TRUE, MyCheck() returns if there

-//           are no un-freed allocations.  If there are un-freed allocations,

-//           they are displayed and exit(1) is called.

-//

-//

-//  File := Set to __FILE__ by macro expansion.

-//

-//  Line := Set to __LINE__ by macro expansion.

-//

-// Returns:

-//

-//  n/a

-//

-// --*/

-//

+

+/**

+  Allocate a new link in the allocation chain along with enough storage

+  for the File[] string, requested Size and alignment overhead.  If

+  memory cannot be allocated or the allocation chain has been corrupted,

+  exit(1) will be called.

+

+  @param Size Number of bytes (UINT8) requested by the called.

+              Size cannot be zero.

+  @param File Set to __FILE__ by macro expansion.

+  @param Line Set to __LINE__ by macro expansion.

+

+  @return Pointer to the caller's buffer.

+**/

 VOID  *

 MyAlloc (

   UINTN      Size,

@@ -110,30 +110,20 @@ MyAlloc (
   UINTN      Line

   )

 ;

-//

-// *++

-// Description:

-//

-//  Allocate a new link in the allocation chain along with enough storage

-//  for the File[] string, requested Size and alignment overhead.  If

-//  memory cannot be allocated or the allocation chain has been corrupted,

-//  exit(1) will be called.

-//

-// Parameters:

-//

-//  Size := Number of bytes (UINT8) requested by the called.

-//          Size cannot be zero.

-//

-//  File := Set to __FILE__ by macro expansion.

-//

-//  Line := Set to __LINE__ by macro expansion.

-//

-// Returns:

-//

-//  Pointer to the caller's buffer.

-//

-// --*/

-//

+

+/**

+  This does a MyAlloc(), memcpy() and MyFree().  There is no optimization

+  for shrinking or expanding buffers.  An invalid parameter will cause

+  MyRealloc() to fail with a call to exit(1).

+

+  @param Ptr Pointer to the caller's buffer to be re-allocated.

+             Ptr cannot be NULL.

+  @param Size Size of new buffer.  Size cannot be zero.

+  @param File Set to __FILE__ by macro expansion.

+  @param Line Set to __LINE__ by macro expansion.

+

+  @return Pointer to new caller's buffer.

+**/

 VOID  *

 MyRealloc (

   VOID       *Ptr,

@@ -142,31 +132,16 @@ MyRealloc (
   UINTN      Line

   )

 ;

-//

-// *++

-// Description:

-//

-//  This does a MyAlloc(), memcpy() and MyFree().  There is no optimization

-//  for shrinking or expanding buffers.  An invalid parameter will cause

-//  MyRealloc() to fail with a call to exit(1).

-//

-// Parameters:

-//

-//  Ptr := Pointer to the caller's buffer to be re-allocated.

-//         Ptr cannot be NULL.

-//

-//  Size := Size of new buffer.  Size cannot be zero.

-//

-//  File := Set to __FILE__ by macro expansion.

-//

-//  Line := Set to __LINE__ by macro expansion.

-//

-// Returns:

-//

-//  Pointer to new caller's buffer.

-//

-// --*/

-//

+

+/**

+  Release a previously allocated buffer.  Invalid parameters will cause

+  MyFree() to fail with an exit(1) call.

+

+  @param Ptr Pointer to the caller's buffer to be freed.

+             A NULL pointer will be ignored.

+  @param File Set to __FILE__ by macro expansion.

+  @param Line Set to __LINE__ by macro expansion.

+**/

 VOID

 MyFree (

   VOID       *Ptr,

@@ -174,28 +149,7 @@ MyFree (
   UINTN      Line

   )

 ;

-//

-// *++

-// Description:

-//

-//  Release a previously allocated buffer.  Invalid parameters will cause

-//  MyFree() to fail with an exit(1) call.

-//

-// Parameters:

-//

-//  Ptr := Pointer to the caller's buffer to be freed.

-//         A NULL pointer will be ignored.

-//

-//  File := Set to __FILE__ by macro expansion.

-//

-//  Line := Set to __LINE__ by macro expansion.

-//

-// Returns:

-//

-//  n/a

-//

-// --*/

-//

+

 #else /* USE_MYALLOC */

 

 //