Fix doxygen comment for structure and macro

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

7 files changed, 99 insertions, 193 deletions

diff --git a/MdePkg/Include/Protocol/BlockIo.h b/MdePkg/Include/Protocol/BlockIo.h
index 8584610a2c..dd3d9c1a15 100644
--- a/MdePkg/Include/Protocol/BlockIo.h
+++ b/MdePkg/Include/Protocol/BlockIo.h
@@ -128,85 +128,77 @@ EFI_STATUS
 

 /**

   Block IO read only mode data and updated only via members of BlockIO

-  

-  @param MediaId

-  The curent media Id. If the media changes, this value is changed.

-  

-  @param RemovableMedia

-  TRUE if the media is removable; otherwise, FALSE.

-  

-  @param MediaPresent

-  TRUE if there is a media currently present in the device;

-  othersise, FALSE. THis field shows the media present status

-  as of the most recent ReadBlocks() or WriteBlocks() call.

-

-  @param LogicalPartition

-  TRUE if LBA 0 is the first block of a partition; otherwise

-  FALSE. For media with only one partition this would be TRUE.

-  

-  @param ReadOnly

-  TRUE if the media is marked read-only otherwise, FALSE.

-  This field shows the read-only status as of the most recent WriteBlocks () call.

-  

-  @param WriteCaching

-  TRUE if the WriteBlock () function caches write data.

-

-  @param BlockSize

-  The intrinsic block size of the device. If the media changes, then

-  this field is updated.  

-

-  @param IoAlign

-  Supplies the alignment requirement for any buffer to read or write block(s).

-  

-  @param LastBlock

-  The last logical block address on the device.

-  If the media changes, then this field is updated.   

-

 **/

 typedef struct {

-  UINT32  MediaId;    

+  ///

+  /// The curent media Id. If the media changes, this value is changed.

+  ///

+  UINT32  MediaId;         

+   

+  ///

+  /// TRUE if the media is removable; otherwise, FALSE.

+  ///    

   BOOLEAN RemovableMedia;

+  

+  ///

+  /// TRUE if there is a media currently present in the device;

+  /// othersise, FALSE. THis field shows the media present status

+  /// as of the most recent ReadBlocks() or WriteBlocks() call.  

+  ///

   BOOLEAN MediaPresent;

+

+  ///

+  /// TRUE if LBA 0 is the first block of a partition; otherwise

+  /// FALSE. For media with only one partition this would be TRUE.

+  ///

   BOOLEAN LogicalPartition;

+  

+  ///

+  /// TRUE if the media is marked read-only otherwise, FALSE.

+  /// This field shows the read-only status as of the most recent WriteBlocks () call.

+  ///

   BOOLEAN ReadOnly;

+  

+  ///

+  /// TRUE if the WriteBlock () function caches write data.

+  ///

   BOOLEAN WriteCaching; 

+  

+  ///

+  /// The intrinsic block size of the device. If the media changes, then

+  /// this field is updated.  

+  ///

   UINT32  BlockSize; 

+  

+  ///

+  /// Supplies the alignment requirement for any buffer to read or write block(s).

+  ///

   UINT32  IoAlign; 

+  

+  ///

+  /// The last logical block address on the device.

+  /// If the media changes, then this field is updated. 

+  ///

   EFI_LBA LastBlock; 

 } EFI_BLOCK_IO_MEDIA;

 

 #define EFI_BLOCK_IO_PROTOCOL_REVISION  0x00010000

-//

-// Revision defined in EFI1.1.

-// 

+

+///

+/// Revision defined in EFI1.1.

+/// 

 #define EFI_BLOCK_IO_INTERFACE_REVISION   EFI_BLOCK_IO_PROTOCOL_REVISION

 

 /**

   @par Protocol Description:

   This protocol provides control over block devices.

-

-  @param Revision 

-  The revision to which the block IO interface adheres. All future

-  revisions must be backwards compatible. If a future version is not

-  back wards compatible, it is not the same GUID.

-  

-  @param Media 

-  A pointer to the EFI_BLOCK_IO_MEDIA data for this device.

-

-  @param Reset 

-  Resets the block device hardware.

-

-  @param ReadBlocks 

-  Reads the requested number of blocks from the device. 

-

-  @param WriteBlocks 

-  Writes the requested number of blocks to the device. 

-

-  @param FlushBlocks 

-  Flushes and cache blocks. This function is optional and only

-  needs to be supported on block devices that cache writes. 

 **/

 struct _EFI_BLOCK_IO_PROTOCOL {

+  ///

+  /// The revision to which the block IO interface adheres. All future

+  /// revisions must be backwards compatible. If a future version is not

+  /// back wards compatible, it is not the same GUID.

+  ///

   UINT64              Revision;

 

   EFI_BLOCK_IO_MEDIA  *Media;

diff --git a/MdePkg/Include/Protocol/BusSpecificDriverOverride.h b/MdePkg/Include/Protocol/BusSpecificDriverOverride.h
index 1f86c315fb..5789a92483 100644
--- a/MdePkg/Include/Protocol/BusSpecificDriverOverride.h
+++ b/MdePkg/Include/Protocol/BusSpecificDriverOverride.h
@@ -65,10 +65,6 @@ EFI_STATUS
   This protocol matches one or more drivers to a controller. This protocol is produced by a bus driver,

   and it is installed on the child handles of buses that require a bus specific algorithm for matching

   drivers to controllers.

-

-  @param GetDriver

-  Uses a bus specific algorithm to retrieve a driver image handle for a controller.

- 

 **/

 struct _EFI_BUS_SPECIFIC_DRIVER_OVERRIDE_PROTOCOL {

   EFI_BUS_SPECIFIC_DRIVER_OVERRIDE_GET_DRIVER GetDriver;

diff --git a/MdePkg/Include/Protocol/ComponentName.h b/MdePkg/Include/Protocol/ComponentName.h
index 98e5b76987..69c61a619e 100644
--- a/MdePkg/Include/Protocol/ComponentName.h
+++ b/MdePkg/Include/Protocol/ComponentName.h
@@ -116,23 +116,15 @@ EFI_STATUS
   @par Protocol Description:

   This protocol is used to retrieve user readable names of drivers 

   and controllers managed by UEFI Drivers.

-

-  @param GetDriverName

-  Retrieves a Unicode string that is the user readable name of the driver.

-  

-  @param GetControllerName

-  Retrieves a Unicode string that is the user readable name of a

-  controller that is being managed by a driver.

-  

-  @param SupportedLanguages 

-  A Null-terminated ASCII string that contains one or more

-  ISO 639-2 language codes. This is the list of language codes

-  that this protocol supports.

-  

 **/

 struct _EFI_COMPONENT_NAME_PROTOCOL {

   EFI_COMPONENT_NAME_GET_DRIVER_NAME      GetDriverName;

   EFI_COMPONENT_NAME_GET_CONTROLLER_NAME  GetControllerName;

+  ///

+  /// A Null-terminated ASCII string that contains one or more

+  /// ISO 639-2 language codes. This is the list of language codes

+  /// that this protocol supports.  

+  ///

   CHAR8                                   *SupportedLanguages;

 };

 

diff --git a/MdePkg/Include/Protocol/ComponentName2.h b/MdePkg/Include/Protocol/ComponentName2.h
index fa5c7a8410..1ee87e9a75 100644
--- a/MdePkg/Include/Protocol/ComponentName2.h
+++ b/MdePkg/Include/Protocol/ComponentName2.h
@@ -158,25 +158,18 @@ EFI_STATUS
   @par Protocol Description:

   This protocol is used to retrieve user readable names of drivers 

   and controllers managed by UEFI Drivers.

-

-  @param GetDriverName

-  Retrieves a Unicode string that is the user readable name of the driver.

-  

-  @param GetControllerName

-  Retrieves a Unicode string that is the user readable name of a

-  controller that is being managed by a driver.

-  

-  @param SupportedLanguages 

-  A Null-terminated ASCII string array that contains one or more

-  supported language codes. This is the list of language codes that

-  this protocol supports. The number of languages supported by a

-  driver is up to the driver writer. SupportedLanguages is

-  specified in RFC 3066 format.

-  

 **/

 struct _EFI_COMPONENT_NAME2_PROTOCOL {

   EFI_COMPONENT_NAME2_GET_DRIVER_NAME      GetDriverName;

   EFI_COMPONENT_NAME2_GET_CONTROLLER_NAME  GetControllerName;

+

+  ///

+  /// A Null-terminated ASCII string array that contains one or more

+  /// supported language codes. This is the list of language codes that

+  /// this protocol supports. The number of languages supported by a

+  /// driver is up to the driver writer. SupportedLanguages is

+  /// specified in RFC 3066 format.  

+  ///

   CHAR8                                    *SupportedLanguages;

 };

 

diff --git a/MdePkg/Include/Protocol/Cpu.h b/MdePkg/Include/Protocol/Cpu.h
index 1cb354c119..d8964bdf6c 100644
--- a/MdePkg/Include/Protocol/Cpu.h
+++ b/MdePkg/Include/Protocol/Cpu.h
@@ -261,52 +261,6 @@ EFI_STATUS
   Foundation. This includes flushing caches, enabling and disabling interrupts, hooking interrupt

   vectors and exception vectors, reading internal processor timers, resetting the processor, and

   determining the processor frequency.

-

-  @param FlushDataCache

-  Flushes a range of the processor's data cache. If the processor does 

-  not contain a data cache, or the data cache is fully coherent, then this 

-  function can just return EFI_SUCCESS. If the processor does not support 

-  flushing a range of addresses from the data cache, then the entire data 

-  cache must be flushed. 

-

-  @param EnableInterrupt   

-  Enables interrupt processing by the processor.

-

-  @param DisableInterrupt  

-  Disables interrupt processing by the processor.

-

-  @param GetInterruptState 

-  Retrieves the processor's current interrupt state.

-

-  @param Init

-  Generates an INIT on the processor. If a processor cannot programmatically 

-  generate an INIT without help from external hardware, then this function 

-  returns EFI_UNSUPPORTED.

-

-  @param RegisterInterruptHandler

-  Associates an interrupt service routine with one of the processor's interrupt 

-  vectors. This function is typically used by the EFI_TIMER_ARCH_PROTOCOL to 

-  hook the timer interrupt in a system. It can also be used by the debugger to 

-  hook exception vectors.

-

-  @param GetTimerValue       

-  Returns the value of one of the processor's internal timers.

-

-  @param SetMemoryAttributes 

-  Attempts to set the attributes of a memory region.

-

-  @param NumberOfTimers

-  The number of timers that are available in a processor. The value in this 

-  field is a constant that must not be modified after the CPU Architectural 

-  Protocol is installed. All consumers must treat this as a read-only field.

-

-  @param DmaBufferAlignment

-  The size, in bytes, of the alignment required for DMA buffer allocations. 

-  This is typically the size of the largest data cache line in the platform. 

-  The value in this field is a constant that must not be modified after the 

-  CPU Architectural Protocol is installed. All consumers must treat this as 

-  a read-only field.

-

 **/

 struct _EFI_CPU_ARCH_PROTOCOL {

   EFI_CPU_FLUSH_DATA_CACHE            FlushDataCache;

@@ -317,7 +271,19 @@ struct _EFI_CPU_ARCH_PROTOCOL {
   EFI_CPU_REGISTER_INTERRUPT_HANDLER  RegisterInterruptHandler;

   EFI_CPU_GET_TIMER_VALUE             GetTimerValue;

   EFI_CPU_SET_MEMORY_ATTRIBUTES       SetMemoryAttributes;

+  ///

+  /// The number of timers that are available in a processor. The value in this 

+  /// field is a constant that must not be modified after the CPU Architectural 

+  /// Protocol is installed. All consumers must treat this as a read-only field.

+  ///

   UINT32                              NumberOfTimers;

+  ///

+  /// The size, in bytes, of the alignment required for DMA buffer allocations. 

+  /// This is typically the size of the largest data cache line in the platform. 

+  /// The value in this field is a constant that must not be modified after the 

+  /// CPU Architectural Protocol is installed. All consumers must treat this as 

+  /// a read-only field.  

+  ///

   UINT32                              DmaBufferAlignment;

 };

 

diff --git a/MdePkg/Include/Protocol/DebugPort.h b/MdePkg/Include/Protocol/DebugPort.h
index edfae57367..e80112744c 100644
--- a/MdePkg/Include/Protocol/DebugPort.h
+++ b/MdePkg/Include/Protocol/DebugPort.h
@@ -119,18 +119,6 @@ EFI_STATUS
 /**

   @par Protocol Description:

   This protocol provides the communication link between the debug agent and the remote host.

-

-  @param Reset

-  Resets the debugport hardware.

-  

-  @param Write

-  Send a buffer of characters to the debugport device.

-

-  @param Read 

-  Receive a buffer of characters from the debugport device.

-

-  @param Poll 

-  Determine if there is any data available to be read from the debugport device.

 **/ 

 struct _EFI_DEBUGPORT_PROTOCOL {

   EFI_DEBUGPORT_RESET Reset;

diff --git a/MdePkg/Include/Protocol/DebugSupport.h b/MdePkg/Include/Protocol/DebugSupport.h
index 79ec7dbdf6..450d6f04ae 100644
--- a/MdePkg/Include/Protocol/DebugSupport.h
+++ b/MdePkg/Include/Protocol/DebugSupport.h
@@ -58,13 +58,13 @@ typedef INTN  EFI_EXCEPTION_TYPE;
 #define EXCEPT_IA32_MACHINE_CHECK   18

 #define EXCEPT_IA32_SIMD            19

 

-//

-//  IA-32 processor context definition

-//

-//

-// FXSAVE_STATE

-// FP / MMX / XMM registers (see fxrstor instruction definition)

-//

+///

+///  IA-32 processor context definition

+///

+///

+/// FXSAVE_STATE

+/// FP / MMX / XMM registers (see fxrstor instruction definition)

+///

 typedef struct {

   UINT16  Fcw;

   UINT16  Fsw;

@@ -152,12 +152,12 @@ typedef struct {
 #define EXCEPT_X64_MACHINE_CHECK   18

 #define EXCEPT_X64_SIMD            19

 

-//

-//  X64 processor context definition

-//

-// FXSAVE_STATE

-// FP / MMX / XMM registers (see fxrstor instruction definition)

-//

+///

+///  X64 processor context definition

+///

+/// FXSAVE_STATE

+/// FP / MMX / XMM registers (see fxrstor instruction definition)

+///

 typedef struct {

   UINT16  Fcw;

   UINT16  Fsw;

@@ -278,9 +278,9 @@ typedef struct {
 #define EXCEPT_IPF_IA32_INTERCEPT 46

 #define EXCEPT_IPF_IA32_INTERRUPT 47

 

-//

-//  IPF processor context definition

-//

+///

+///  IPF processor context definition

+///

 typedef struct {

   //

   // The first reserved field is necessary to preserve alignment for the correct

@@ -510,14 +510,14 @@ VOID
   IN OUT EFI_SYSTEM_CONTEXT               SystemContext

   );

 

-//

-// Machine type definition

-//

+///

+/// Machine type definition

+///

 typedef enum {

-  IsaIa32 = IMAGE_FILE_MACHINE_I386, // 0x014C

-  IsaX64  = IMAGE_FILE_MACHINE_X64,   // 0x8664

-  IsaIpf  = IMAGE_FILE_MACHINE_IA64,  // 0x0200

-  IsaEbc  = IMAGE_FILE_MACHINE_EBC    // 0x0EBC

+  IsaIa32 = IMAGE_FILE_MACHINE_I386,  ///< 0x014C

+  IsaX64  = IMAGE_FILE_MACHINE_X64,   ///< 0x8664

+  IsaIpf  = IMAGE_FILE_MACHINE_IA64,  ///< 0x0200

+  IsaEbc  = IMAGE_FILE_MACHINE_EBC    ///< 0x0EBC

 } EFI_INSTRUCTION_SET_ARCHITECTURE;

 

 

@@ -621,27 +621,6 @@ EFI_STATUS
   This protocol provides the services to allow the debug agent to register 

   callback functions that are called either periodically or when specific 

   processor exceptions occur.

-

-  @param Isa

-  Declares the processor architecture for this instance of the EFI

-  Debug Support protocol.

-

-  @param GetMaximumProcessorIndex

-  Returns the maximum processor index value that may be used.

-

-  @param RegisterPeriodicCallback

-  Registers a callback function that will be invoked periodically

-  and asynchronously to the execution of EFI.

-

-  @param RegisterExceptionCallback

-  Registers a callback function that will be called each time the

-  specified processor exception occurs.

-

-  @param InvalidateInstructionCache

-  Invalidate the instruction cache of the processor. This is required

-  by processor architectures where instruction and data caches are

-  not coherent when instructions in the code under debug has been

-  modified by the debug agent.

 **/

 struct _EFI_DEBUG_SUPPORT_PROTOCOL {

   EFI_INSTRUCTION_SET_ARCHITECTURE  Isa;