Documentation cleanup: now have a Doxygen brief description for all c…

…lasses, plus a Doxyfile for generating documentation
azonenberg · Aug 3, 2018 · 68b7060 · 68b7060
1 parent eea5ae8
commit 68b7060
Show file tree

Hide file tree

Showing 16 changed files with 2,534 additions and 17 deletions.
diff --git a/ARMCoreSightDevice.h b/ARMCoreSightDevice.h
@@ -30,11 +30,16 @@
 /**
 	@file
 	@author Andrew D. Zonenberg
-	@brief Base class for ARM CoreSight components (other than CPU cores) on a debug APB bus
+	@brief Declaration of ARMCoreSightDevice
  */
 #ifndef ARMCoreSightDevice_h
 #define ARMCoreSightDevice_h
 
+/**
+	@brief Base class for ARM CoreSight components (other than CPU cores) on a debug APB bus
+
+	\ingroup libjtaghal
+ */
 class ARMCoreSightDevice : public ARMAPBDevice
 {
 public:

diff --git a/ARMDebugAccessPort.h b/ARMDebugAccessPort.h
@@ -75,7 +75,7 @@ union ARMDebugPortIDRegister
 } __attribute__ ((packed));
 
 /**
-	@brief An AP attached to an ADIv5 DP
+	@brief Base class for all access ports within an ARMDebugPort
 
 	\ingroup libjtaghal
  */

diff --git a/ARMDebugMemAccessPort.h b/ARMDebugMemAccessPort.h
@@ -39,7 +39,7 @@
 #include <stdlib.h>
 
 /**
-	@brief ARM debug port identification register (see ADIv5 Architecture Specification figure 6-3)
+	@brief Contents of the CSW register in a MEM-AP (see ADIv5 Architecture Specification 7.6.4)
  */
 union ARMDebugMemAPControlStatusWord
 {
@@ -90,7 +90,7 @@ class ARMDebugAccessPort;
 class ARMAPBDevice;
 
 /**
-	@brief A memory mapped debug interface
+	@brief A bridge from an ARMDebugPort to an ARM memory bus
 
 	\ingroup libjtaghal
  */

diff --git a/ARMDebugPort.h b/ARMDebugPort.h
@@ -36,6 +36,11 @@
 #ifndef ARMDebugPort_h
 #define ARMDebugPort_h
 
+/**
+	@brief Base class for ARM debug ports (JTAG-DP, SWJ-DP, etc)
+
+	\ingroup libjtaghal
+ */
 class ARMDebugPort		: public DebuggerInterface
 {
 public:

diff --git a/ARMDevice.h b/ARMDevice.h
@@ -45,7 +45,7 @@ enum ARM_IDCODES
 };
 
 /**
-	@brief Abstract base class for all ARM Ltd devices (typically ARM DAPs)
+	@brief Abstract base class for all ARM Ltd JTAG devices (ADIv5 DAP or legacy CPUs with their own JTAG TAPs)
 
 	\ingroup libjtaghal
  */

diff --git a/ARMFlashPatchBreakpoint.h b/ARMFlashPatchBreakpoint.h
@@ -30,13 +30,18 @@
 /**
 	@file
 	@author Andrew D. Zonenberg
-	@brief ARMv7-M Flash Patch/Breakpoint Unit
+	@brief Declaration of ARMFlashPatchBreakpoint
  */
 #ifndef ARMFlashPatchBreakpoint_h
 #define ARMFlashPatchBreakpoint_h
 
 class ARMv7MProcessor;
 
+/**
+	@brief Cortex-M Flash Patch/Breakpoint Unit (see ARMv7-M architecture ref C1.11)
+
+	\ingroup libjtaghal
+ */
 class ARMFlashPatchBreakpoint : public ARMCoreSightDevice
 {
 public:

diff --git a/ARMJtagDebugPort.h b/ARMJtagDebugPort.h
@@ -106,7 +106,7 @@ union ARMJtagDebugPortStatusRegister
 class ARMDebugMemAccessPort;
 
 /**
-	@brief An ARM debug port (contains one or more APs and a DP)
+	@brief An ARM JTAG-DP (contains one or more APs and a DP)
 
 	\ingroup libjtaghal
  */

diff --git a/ARMv7MProcessor.h b/ARMv7MProcessor.h
@@ -40,7 +40,7 @@ class DebuggableDevice;
 class ARMAPBDevice;
 
 /**
-	@brief An ARM Cortex-M CPU core supporting the ARMv7-M architecture, as seen over a CoreSight APB bus
+	@brief An ARMv7 Cortex-M CPU core, as seen over a CoreSight APB bus
 
 	\ingroup libjtaghal
  */

diff --git a/ARMv7Processor.h b/ARMv7Processor.h
@@ -58,7 +58,7 @@ enum ARMDebugArchVersion
 };
 
 /**
-	@brief ARM debug ID register (see ARMv7 ARM, C11.11.15)
+	@brief ARM debug ID register (see ARMv7 Architecture Reference Manual, C11.11.15)
  */
 union ARMv7DebugIDRegister
 {
@@ -104,7 +104,7 @@ union ARMv7DebugIDRegister
 } __attribute__ ((packed));
 
 /**
-	ARM debug status/control register (see ARMv7 ARM, C11.11.20)
+	@brief ARM debug status/control register (see ARMv7 Architecture Reference Manual, C11.11.20)
  */
 union ARMv7DebugStatusControlRegister
 {
@@ -192,7 +192,7 @@ union ARMv7DebugStatusControlRegister
 } __attribute__ ((packed));
 
 /**
-	@brief An ARM Cortex-A9 CPU core, as seen over a CoreSight APB bus
+	@brief An ARMv7 Cortex-A CPU core, as seen over a CoreSight APB bus
 
 	\ingroup libjtaghal
  */

diff --git a/ARMv8Processor.h b/ARMv8Processor.h
@@ -58,7 +58,7 @@ enum ARMDebugArchVersion
 };
 */
 /**
-	@brief ARM debug ID register (see ARMv8 ARM, C11.11.15)
+	ARM debug ID register (see ARMv8 ARM, C11.11.15)
  */
 /*
 union ARMv8DebugIDRegister
@@ -194,7 +194,7 @@ union ARMv8DebugStatusControlRegister
 } __attribute__ ((packed));
 */
 /**
-	@brief An ARM Cortex-A9 CPU core, as seen over a CoreSight APB bus
+	@brief An ARMv8 Cortex-A CPU core, as seen over a CoreSight APB bus
 
 	\ingroup libjtaghal
  */

diff --git a/DebuggableDevice.h b/DebuggableDevice.h
@@ -39,7 +39,7 @@
 class DebuggerInterface;
 
 /**
-	@brief Generic base class for all debuggable devices (MCUs etc)
+	@brief Generic base class for all debuggable devices (CPU cores etc)
 
 	\ingroup libjtaghal
  */