Fix doxygen comment for structure and macro

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

14 files changed, 90 insertions, 253 deletions

diff --git a/MdePkg/Include/Protocol/Decompress.h b/MdePkg/Include/Protocol/Decompress.h
index 0cc9bb7e36..5b2291f177 100644
--- a/MdePkg/Include/Protocol/Decompress.h
+++ b/MdePkg/Include/Protocol/Decompress.h
@@ -113,17 +113,6 @@ EFI_STATUS
   @par Protocol Description:

   Provides a decompression service.

 

-  @param GetInfo

-  Given the compressed source buffer, this function retrieves the

-  size of the uncompressed destination buffer and the size of the

-  scratch buffer required to perform the decompression. It is the

-  caller's responsibility to allocate the destination buffer and the

-  scratch buffer prior to calling EFI_DECOMPRESS_PROTOCOL.Decompress().

-

-  @param Decompresss

-  Decompresses a compressed source buffer into an uncompressed

-  destination buffer. It is the caller's responsibility to allocate the

-  destination buffer and a scratch buffer prior to making this call.

 **/ 

 struct _EFI_DECOMPRESS_PROTOCOL {

   EFI_DECOMPRESS_GET_INFO   GetInfo;

diff --git a/MdePkg/Include/Protocol/DeviceIo.h b/MdePkg/Include/Protocol/DeviceIo.h
index 7b79d2355f..6ae0c23884 100644
--- a/MdePkg/Include/Protocol/DeviceIo.h
+++ b/MdePkg/Include/Protocol/DeviceIo.h
@@ -217,39 +217,19 @@ EFI_STATUS
   @par Protocol Description:

   This protocol provides the basic Memory, I/O, and PCI interfaces that 

   are used to abstract accesses to devices.

-

-  @param Mem 

-  Allows reads and writes to memory mapped I/O space.

-

-  @param Io 

-  Allows reads and writes to I/O space.

-

-  @param Pci 

-  Allows reads and writes to PCI configuration space.

-

-  @param Map 

-  Provides the device specific addresses needed to access system memory for DMA. 

-

-  @param PciDevicePath 

-  Provides an EFI Device Path for a PCI device with the given PCI

-  configuration space address.

-

-  @param Unmap 

-  Releases any resources allocated by Map(). 

-

-  @param AllocateBuffer 

-  Allocates pages that are suitable for a common buffer mapping. 

-

-  @param Flush 

-  Flushes any posted write data to the device. 

-

-  @param FreeBuffer 

-  Free pages that were allocated with AllocateBuffer(). 

-

 **/ 

 struct _EFI_DEVICE_IO_PROTOCOL {

+  ///

+  /// Allows reads and writes to memory mapped I/O space.

+  ///

   EFI_IO_ACCESS           Mem;

+  ///

+  /// Allows reads and writes to I/O space.

+  ///

   EFI_IO_ACCESS           Io;

+  ///

+  /// Allows reads and writes to PCI configuration space.

+  ///

   EFI_IO_ACCESS           Pci;

   EFI_IO_MAP              Map;

   EFI_PCI_DEVICE_PATH     PciDevicePath;

diff --git a/MdePkg/Include/Protocol/DevicePathFromText.h b/MdePkg/Include/Protocol/DevicePathFromText.h
index 7c4a161483..327c5e27a3 100644
--- a/MdePkg/Include/Protocol/DevicePathFromText.h
+++ b/MdePkg/Include/Protocol/DevicePathFromText.h
@@ -64,13 +64,6 @@ EFI_DEVICE_PATH_PROTOCOL*
 /**

   @par Protocol Description:

   This protocol converts text to device paths and device nodes.

-

-  @param ConvertTextToDeviceNode

-  Convert text to a device node.

-  

-  @param ConvertTextToDevicePath

-  Convert text to a device path

-  

 **/   

 typedef struct {

   EFI_DEVICE_PATH_FROM_TEXT_NODE  ConvertTextToDeviceNode;

diff --git a/MdePkg/Include/Protocol/DevicePathToText.h b/MdePkg/Include/Protocol/DevicePathToText.h
index 4a8353181f..853e43e133 100644
--- a/MdePkg/Include/Protocol/DevicePathToText.h
+++ b/MdePkg/Include/Protocol/DevicePathToText.h
@@ -75,13 +75,6 @@ CHAR16*
 /**

   @par Protocol Description:

   This protocol converts device paths and device nodes to text.

-

-  @param ConvertTextToDeviceNode

-  Convert the device node to text.

-  

-  @param ConvertTextToDevicePath

-  Convert the device path to text.

-  

 **/

 typedef struct {

   EFI_DEVICE_PATH_TO_TEXT_NODE        ConvertDeviceNodeToText;

diff --git a/MdePkg/Include/Protocol/DevicePathUtilities.h b/MdePkg/Include/Protocol/DevicePathUtilities.h
index 44e88ee315..8d98add591 100644
--- a/MdePkg/Include/Protocol/DevicePathUtilities.h
+++ b/MdePkg/Include/Protocol/DevicePathUtilities.h
@@ -173,30 +173,6 @@ BOOLEAN
 /**

   @par Protocol Description:

   This protocol is used to creates and manipulates device paths and device nodes.

-

-  @param GetDevicePathSize 

-  Returns the size of the specified device path, in bytes.

-

-  @param DuplicateDevicePath

-  Duplicates a device path structure.

- 

-  @param AppendDeviceNode 

-  Appends the device node to the specified device path.

-

-  @param AppendDevicePath 

-  Appends the device path to the specified device path.

-

-  @param AppendDevicePathInstance

-  Appends a device path instance to another device path.

-

-  @param GetNextDevicePathInstance

-  Retrieves the next device path instance from a device path data structure.

-

-  @param IsDevicePathMultiInstance

-  Returns TRUE if this is a multi-instance device path.

-

-  @param CreateDeviceNode 

-  Allocates memory for a device node with the specified type and sub-type.

 **/ 

 typedef struct {

   EFI_DEVICE_PATH_UTILS_GET_DEVICE_PATH_SIZE GetDevicePathSize;

diff --git a/MdePkg/Include/Protocol/Dhcp4.h b/MdePkg/Include/Protocol/Dhcp4.h
index e7fc60ecde..2031f2b5da 100644
--- a/MdePkg/Include/Protocol/Dhcp4.h
+++ b/MdePkg/Include/Protocol/Dhcp4.h
@@ -49,11 +49,11 @@ typedef struct {
     UINT32            Xid;

     UINT16            Seconds;

     UINT16            Reserved;

-    EFI_IPv4_ADDRESS  ClientAddr;       //Client IP address from client

-    EFI_IPv4_ADDRESS  YourAddr;         //Client IP address from server

-    EFI_IPv4_ADDRESS  ServerAddr;       //IP address of next server in bootstrap

-    EFI_IPv4_ADDRESS  GatewayAddr;      //Relay agent IP address

-    UINT8             ClientHwAddr[16]; //Client hardware address

+    EFI_IPv4_ADDRESS  ClientAddr;       ///< Client IP address from client

+    EFI_IPv4_ADDRESS  YourAddr;         ///< Client IP address from server

+    EFI_IPv4_ADDRESS  ServerAddr;       ///< IP address of next server in bootstrap

+    EFI_IPv4_ADDRESS  GatewayAddr;      ///< Relay agent IP address

+    UINT8             ClientHwAddr[16]; ///< Client hardware address

     CHAR8             ServerName[64];

     CHAR8             BootFileName[128];

 }EFI_DHCP4_HEADER;

@@ -415,37 +415,6 @@ EFI_STATUS
   @par Protocol Description:

   This protocol is used to collect configuration information for the EFI IPv4 Protocol drivers

   and to provide DHCPv4 server and PXE boot server discovery services.

-

-  @param GetModeData 

-  Gets the EFI DHCPv4 Protocol driver status and operational data.

-

-  @param Configure 

-  Initializes, changes, or resets operational settings for the EFI

-  DHCPv4 Protocol driver.

-  

-  @param Start

-  Starts the DHCP configuration process. 

-  

-  @param RenewRebind 

-  Tries to manually extend the lease time by sending a request packet.

-

-  @param Release 

-  Releases the current configuration and returns the EFI DHCPv4

-  Protocol driver to the initial state.

-  

-  @param Stop

-  Stops the DHCP configuration process no matter what state the

-  driver is in. After being stopped, this driver will not automatically

-  communicate with the DHCP server.

-  

-  @param Build 

-  Puts together a DHCP or PXE packet. 

-  

-  @param TransmitReceive 

-  Transmits a DHCP or PXE packet and waits for response packets.

-

-  @param Parse 

-  Parses the packed DHCP or PXE option data. 

 **/

 struct _EFI_DHCP4_PROTOCOL {

   EFI_DHCP4_GET_MODE_DATA      GetModeData;

diff --git a/MdePkg/Include/Protocol/DiskIo.h b/MdePkg/Include/Protocol/DiskIo.h
index fbf4384874..23c7258434 100644
--- a/MdePkg/Include/Protocol/DiskIo.h
+++ b/MdePkg/Include/Protocol/DiskIo.h
@@ -101,20 +101,13 @@ EFI_STATUS
 /**

   @par Protocol Description:

   This protocol is used to abstract Block I/O interfaces.

-

-  @param Revision 

-  The revision to which the disk I/O interface adheres. All future

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

-  backwards compatible, it is not the same GUID.

-

-  @param ReadDisk 

-  Reads data from the disk.

-  

-  @param WriteDisk 

-  Writes data to the disk.

-

 **/

 struct _EFI_DISK_IO_PROTOCOL {

+  ///

+  /// The revision to which the disk I/O interface adheres. All future

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

+  /// backwards compatible, it is not the same GUID.

+  ///

   UINT64          Revision;

   EFI_DISK_READ   ReadDisk;

   EFI_DISK_WRITE  WriteDisk;

diff --git a/MdePkg/Include/Protocol/DriverBinding.h b/MdePkg/Include/Protocol/DriverBinding.h
index 6f6ddf6ad1..43fc16593b 100644
--- a/MdePkg/Include/Protocol/DriverBinding.h
+++ b/MdePkg/Include/Protocol/DriverBinding.h
@@ -30,7 +30,12 @@
 typedef struct _EFI_DRIVER_BINDING_PROTOCOL  EFI_DRIVER_BINDING_PROTOCOL;

 

 /**

-  Test to see if this driver supports ControllerHandle. 

+  Test to see if this driver supports ControllerHandle. This service

+  is called by the EFI boot service ConnectController(). In

+  order to make drivers as small as possible, there are a few calling

+  restrictions for this service. ConnectController() must

+  follow these calling restrictions. If any other agent wishes to call

+  Supported() it must also follow these calling restrictions.

 

   @param  This                Protocol instance pointer.

   @param  ControllerHandle    Handle of device to test

@@ -51,7 +56,12 @@ EFI_STATUS
   );

 

 /**

-  Start this driver on ControllerHandle.

+  Start this driver on ControllerHandle. This service is called by the

+  EFI boot service ConnectController(). In order to make

+  drivers as small as possible, there are a few calling restrictions for

+  this service. ConnectController() must follow these

+  calling restrictions. If any other agent wishes to call Start() it

+  must also follow these calling restrictions.

 

   @param  This                 Protocol instance pointer.

   @param  ControllerHandle     Handle of device to bind driver to

@@ -72,8 +82,13 @@ EFI_STATUS
   );

 

 /**

-  Stop this driver on ControllerHandle.

-

+  Stop this driver on ControllerHandle. This service is called by the

+  EFI boot service DisconnectController(). In order to

+  make drivers as small as possible, there are a few calling

+  restrictions for this service. DisconnectController()

+  must follow these calling restrictions. If any other agent wishes

+  to call Stop() it must also follow these calling restrictions.

+  

   @param  This              Protocol instance pointer.

   @param  ControllerHandle  Handle of device to stop driver on

   @param  NumberOfChildren  Number of Handles in ChildHandleBuffer. If number of

@@ -100,63 +115,40 @@ EFI_STATUS
   @par Protocol Description:

   This protocol provides the services required to determine if a driver supports a given controller. 

   If a controller is supported, then it also provides routines to start and stop the controller.

-  

-  @param Supported 

-  Tests to see if this driver supports a given controller. This service

-  is called by the EFI boot service ConnectController(). In

-  order to make drivers as small as possible, there are a few calling

-  restrictions for this service. ConnectController() must

-  follow these calling restrictions. If any other agent wishes to call

-  Supported() it must also follow these calling restrictions.

-

-

-  @param Start 

-  Starts a controller using this driver. This service is called by the

-  EFI boot service ConnectController(). In order to make

-  drivers as small as possible, there are a few calling restrictions for

-  this service. ConnectController() must follow these

-  calling restrictions. If any other agent wishes to call Start() it

-  must also follow these calling restrictions. 

-  

-  @param Stop 

-  Stops a controller using this driver. This service is called by the

-  EFI boot service DisconnectController(). In order to

-  make drivers as small as possible, there are a few calling

-  restrictions for this service. DisconnectController()

-  must follow these calling restrictions. If any other agent wishes

-  to call Stop() it must also follow these calling restrictions.

-  

-  @param Version 

-  The version number of the UEFI driver that produced the

-  EFI_DRIVER_BINDING_PROTOCOL. This field is used by

-  the EFI boot service ConnectController() to determine

-  the order that driver's Supported() service will be used when

-  a controller needs to be started. EFI Driver Binding Protocol

-  instances with higher Version values will be used before ones

-  with lower Version values. The Version values of 0x0-

-  0x0f and 0xfffffff0-0xffffffff are reserved for

-  platform/OEM specific drivers. The Version values of 0x10-

-  0xffffffef are reserved for IHV-developed drivers.

-  

-  @param ImageHandle 

-  The image handle of the UEFI driver that produced this instance

-  of the EFI_DRIVER_BINDING_PROTOCOL.

-  

-  @param DriverBindingHandle

-  The handle on which this instance of the

-  EFI_DRIVER_BINDING_PROTOCOL is installed. In most

-  cases, this is the same handle as ImageHandle. However, for

-  UEFI drivers that produce more than one instance of the

-  EFI_DRIVER_BINDING_PROTOCOL, this value may not be

-  the same as ImageHandle.

-

 **/

 struct _EFI_DRIVER_BINDING_PROTOCOL {

   EFI_DRIVER_BINDING_SUPPORTED  Supported;

   EFI_DRIVER_BINDING_START      Start;

   EFI_DRIVER_BINDING_STOP       Stop;

+  

+  ///

+  /// The version number of the UEFI driver that produced the

+  /// EFI_DRIVER_BINDING_PROTOCOL. This field is used by

+  /// the EFI boot service ConnectController() to determine

+  /// the order that driver's Supported() service will be used when

+  /// a controller needs to be started. EFI Driver Binding Protocol

+  /// instances with higher Version values will be used before ones

+  /// with lower Version values. The Version values of 0x0-

+  /// 0x0f and 0xfffffff0-0xffffffff are reserved for

+  /// platform/OEM specific drivers. The Version values of 0x10-

+  /// 0xffffffef are reserved for IHV-developed drivers.

+  ///

   UINT32                        Version;

+  

+  ///

+  /// The image handle of the UEFI driver that produced this instance

+  /// of the EFI_DRIVER_BINDING_PROTOCOL.

+  ///

   EFI_HANDLE                    ImageHandle;

+  

+  ///

+  /// The handle on which this instance of the

+  /// EFI_DRIVER_BINDING_PROTOCOL is installed. In most

+  /// cases, this is the same handle as ImageHandle. However, for

+  /// UEFI drivers that produce more than one instance of the

+  /// EFI_DRIVER_BINDING_PROTOCOL, this value may not be

+  /// the same as ImageHandle.  

+  ///

   EFI_HANDLE                    DriverBindingHandle;

 };

 

diff --git a/MdePkg/Include/Protocol/DriverConfiguration.h b/MdePkg/Include/Protocol/DriverConfiguration.h
index 7c7eca4531..172b61ef0c 100644
--- a/MdePkg/Include/Protocol/DriverConfiguration.h
+++ b/MdePkg/Include/Protocol/DriverConfiguration.h
@@ -24,7 +24,6 @@
   { \

     0x107a772b, 0xd5e1, 0x11d4, {0x9a, 0x46, 0x0, 0x90, 0x27, 0x3f, 0xc1, 0x4d } \

   }

-

  

 typedef struct _EFI_DRIVER_CONFIGURATION_PROTOCOL  EFI_DRIVER_CONFIGURATION_PROTOCOL;

 

@@ -153,24 +152,16 @@ EFI_STATUS
   @par Protocol Description:  

   Used to set configuration options for a controller that an EFI Driver is managing.

 

-  @param SetOptions          Allows the use to set drivers specific configuration 

-                             options for a controller that the driver is currently managing.

-                             

-  @param OptionsValid        Tests to see if a controller's current configuration 

-                             options are valid. 

-                             

-  @param ForceDefaults       Forces a driver to set the default configuration options 

-                             for a controller.

-

-  @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_DRIVER_CONFIGURATION_PROTOCOL {

   EFI_DRIVER_CONFIGURATION_SET_OPTIONS    SetOptions;

   EFI_DRIVER_CONFIGURATION_OPTIONS_VALID  OptionsValid;

   EFI_DRIVER_CONFIGURATION_FORCE_DEFAULTS ForceDefaults;

+  ///

+  /// 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/DriverConfiguration2.h b/MdePkg/Include/Protocol/DriverConfiguration2.h
index 4ae1d0235a..30b9d7ff98 100644
--- a/MdePkg/Include/Protocol/DriverConfiguration2.h
+++ b/MdePkg/Include/Protocol/DriverConfiguration2.h
@@ -160,32 +160,18 @@ EFI_STATUS
 

   @par Protocol Description:  

   Used to set configuration options for a controller that an EFI Driver is managing.

-

-  @param SetOptions          Allows the use to set drivers specific configuration 

-                             options for a controller that the driver is currently managing.

-                             

-  @param OptionsValid        Tests to see if a controller's current configuration 

-                             options are valid. 

-                             

-  @param ForceDefaults       Forces a driver to set the default configuration options 

-                             for a controller.

-

-  @param SupportedLanguages  A Null-terminated ASCII string that

-                             contains one or more RFC 3066

-                             language codes.  This is the list

-                             of language codes that this

-                             protocol supports.

-

 **/

 struct _EFI_DRIVER_CONFIGURATION2_PROTOCOL {

   EFI_DRIVER_CONFIGURATION2_SET_OPTIONS     SetOptions;

   EFI_DRIVER_CONFIGURATION2_OPTIONS_VALID   OptionsValid;

   EFI_DRIVER_CONFIGURATION2_FORCE_DEFAULTS  ForceDefaults;

+  ///

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

+  /// language codes.  This is the list of language codes that this protocol supports.  

+  ///

   CHAR8                                     *SupportedLanguages;

 };

 

-

-

 extern EFI_GUID gEfiDriverConfiguration2ProtocolGuid;

 

 #endif

diff --git a/MdePkg/Include/Protocol/DriverDiagnostics.h b/MdePkg/Include/Protocol/DriverDiagnostics.h
index 6c794be50d..1bd2383dd3 100644
--- a/MdePkg/Include/Protocol/DriverDiagnostics.h
+++ b/MdePkg/Include/Protocol/DriverDiagnostics.h
@@ -97,24 +97,18 @@ EFI_STATUS
   OUT CHAR16                                                **Buffer

   );

 

-

-//

-//

-

 /**

   Interface structure for the Driver Diagnostics Protocol.

 

   @par Protocol Description:

   Used to perform diagnostics on a controller that an EFI Driver is managing.

-

-  @param RunDiagnostics      Runs diagnostics on a controller.

-  @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_DRIVER_DIAGNOSTICS_PROTOCOL {

   EFI_DRIVER_DIAGNOSTICS_RUN_DIAGNOSTICS  RunDiagnostics;

+  ///

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

+  /// language codes.  This is the list of language codes that this protocol supports.  

+  ///  

   CHAR8                                   *SupportedLanguages;

 };

 

diff --git a/MdePkg/Include/Protocol/DriverDiagnostics2.h b/MdePkg/Include/Protocol/DriverDiagnostics2.h
index 99ae5d0807..f8bd6206b2 100644
--- a/MdePkg/Include/Protocol/DriverDiagnostics2.h
+++ b/MdePkg/Include/Protocol/DriverDiagnostics2.h
@@ -91,26 +91,18 @@ EFI_STATUS
   OUT CHAR16                                                **Buffer

   );

 

-

-//

-//

-

 /**

   Interface structure for the Driver Diagnostics2 Protocol.

 

   @par Protocol Description:

   Used to perform diagnostics on a controller that an EFI Driver is managing.

-

-  @param RunDiagnostics      Runs diagnostics on a controller.

-  @param SupportedLanguages  A Null-terminated ASCII string that

-                             contains one or more RFC 3066

-                             language codes.  This is the list

-                             of language codes that this

-                             protocol supports.

-

 **/

 struct _EFI_DRIVER_DIAGNOSTICS2_PROTOCOL {

   EFI_DRIVER_DIAGNOSTICS2_RUN_DIAGNOSTICS RunDiagnostics;

+  ///

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

+  /// language codes.  This is the list of language codes that this protocol supports.  

+  ///    

   CHAR8                                   *SupportedLanguages;

 };

 

diff --git a/MdePkg/Include/Protocol/DriverHealth.h b/MdePkg/Include/Protocol/DriverHealth.h
index 2b889023f5..f7bf0b857e 100644
--- a/MdePkg/Include/Protocol/DriverHealth.h
+++ b/MdePkg/Include/Protocol/DriverHealth.h
@@ -232,15 +232,6 @@ EFI_STATUS
   configuration changes to take affect.  Figure 2-1 below shows all the possible 

   health states of a controller and the legal transitions between the health states. 

 

-  @param GetHealthStatus     Retrieves the health status of a controller in the 

-                             platform.  This function can also optionally return 

-                             warning messages, error messages, and a set of HII 

-                             Forms that may be repair a controller that is not 

-                             properly configured.

-  @param Repair              Performs a repair operation on a controller in the 

-                             platform.  This function can optionally report repair 

-                             progress information back to the platform.

-

 **/

 struct _EFI_DRIVER_HEALTH_PROTOCOL {

   EFI_DRIVER_HEALTH_GET_HEALTH_STATUS  GetHealthStatus;

diff --git a/MdePkg/Include/Protocol/DriverSupportedEfiVersion.h b/MdePkg/Include/Protocol/DriverSupportedEfiVersion.h
index 3bd3e00bae..3592198cf7 100644
--- a/MdePkg/Include/Protocol/DriverSupportedEfiVersion.h
+++ b/MdePkg/Include/Protocol/DriverSupportedEfiVersion.h
@@ -29,19 +29,17 @@
   specification it conforms to. This protocol must be placed on   

   the drivers image handle when the driver's entry point is   

   called.

-  

-  @param Length The size, in bytes, of the entire structure.

-                Future versions of this specification may grow

-                the size of the structure.

-  

-  @param FirmwareVersion The version of the EFI specification

-                         that this driver conforms to.

-                         EFI_2_10_SYSTEM_TABLE_REVISION for this

-                         version of this specification.

-

 **/ 

 typedef struct _EFI_DRIVER_SUPPORTED_EFI_VERSION_PROTOCOL {

+  ///

+  /// The size, in bytes, of the entire structure. Future versions of this 

+  /// specification may grow the size of the structure.

+  /// 

   UINT32 Length;

+  ///

+  /// The version of the EFI specification that this driver conforms to.

+  /// EFI_2_10_SYSTEM_TABLE_REVISION for this version of this specification.  

+  ///

   UINT32 FirmwareVersion;

 } EFI_DRIVER_SUPPORTED_EFI_VERSION_PROTOCOL;