From 166ff13fe8c7945058355b9fa2e10ae8e8c6bdfe Mon Sep 17 00:00:00 2001
From: Russ Butler <russ.butler@arm.com>
Date: Wed, 8 May 2019 13:15:42 -0500
Subject: [PATCH] Add missing documentation

Add documentation to the MbedTester class and the test_utils.h file.
---
 .../MbedTester.h                              | 42 ++++++++++++++++
 .../test_utils.h                              | 49 +++++++++++++++++++
 2 files changed, 91 insertions(+)

diff --git a/components/testing/COMPONENT_FPGA_CI_TEST_SHIELD/MbedTester.h b/components/testing/COMPONENT_FPGA_CI_TEST_SHIELD/MbedTester.h
index 15ddf4db21..f75bad9a11 100644
--- a/components/testing/COMPONENT_FPGA_CI_TEST_SHIELD/MbedTester.h
+++ b/components/testing/COMPONENT_FPGA_CI_TEST_SHIELD/MbedTester.h
@@ -23,6 +23,48 @@
 #include "platform/Callback.h"
 #include "drivers/DigitalInOut.h"
 
+/**
+ * The base class for controlling the FPGA CI Test Shield
+ *
+ * This is the primary interface to the FPGA CI Test Shield. It contains
+ * all the code to communicate with the FPGA. It also provides high level
+ * helper functions, such as functions to setup pin multiplexing, to
+ * select the currently active peripheral and to perform software updates.
+ *
+ * Subclasses can inherit from this class and provide further functionality,
+ * such as the ability to test SPI.
+ *
+ * @note Synchronization level: Not protected
+ *
+ * Example of how to toggle Arduino pin D6 from the FPGA cI Test Shield:
+ * @code
+ * #include "mbed.h"
+ * #include "MbedTester.h"
+ *
+ * const PinList *form_factor = pinmap_ff_default_pins();
+ * const PinList *restricted = pinmap_restricted_pins();
+ * MbedTester tester(form_factor, restricted);
+ *
+ * int main() {
+ *     // Reset the FPGA CI Test Shield to put it into a known state
+ *     tester.reset();
+ *
+ *     // Select the GPIO peripheral
+ *     tester.select_peripheral(MbedTester::PeripheralGPIO);
+ *
+ *     // Map D6 to LogicalPinGPIO0
+ *     tester.pin_map_set(D6, MbedTester::LogicalPinGPIO0);
+ *
+ *     // Toggle the LED
+ *     int toggle = 0;
+ *     while (1) {
+ *         tester.gpio_write(MbedTester::LogicalPinGPIO0, toggle, true);
+ *         wait(0.5);
+ *         toggle = !toggle;
+ *     }
+ * }
+ * @endcode
+ */
 class MbedTester {
 public:
 
diff --git a/components/testing/COMPONENT_FPGA_CI_TEST_SHIELD/test_utils.h b/components/testing/COMPONENT_FPGA_CI_TEST_SHIELD/test_utils.h
index da4185454f..5b5c25df8f 100644
--- a/components/testing/COMPONENT_FPGA_CI_TEST_SHIELD/test_utils.h
+++ b/components/testing/COMPONENT_FPGA_CI_TEST_SHIELD/test_utils.h
@@ -226,6 +226,17 @@ void test_all_peripherals(std::list<PortType> &matched_ports, std::list<PortType
     }
 }
 
+/**
+ * Test function for all pinouts of all peripherals of a given type
+ *
+ * This template function takes in three template parameters:
+ * - PortType - The type of peripheral to test
+ * - FormFactorType - The form factor to test on
+ * - f - The test function to run.
+ *
+ * This function is calls the test function multiple times with
+ * the appropriate combinations of pins.
+ */
 template<typename PortType, typename FormFactorType, typename PortType::TestFunctionType f>
 void all_ports()
 {
@@ -236,6 +247,17 @@ void all_ports()
     test_all_ports<PortType, FormFactorType, typename PortType::TestFunctionType, f>(matched_ports, not_matched_ports);
 }
 
+/**
+ * Test function for one pinout of all peripherals of a given type
+ *
+ * This template function takes in three template parameters:
+ * - PortType - The type of peripheral to test
+ * - FormFactorType - The form factor to test on
+ * - f - The test function to run.
+ *
+ * This function is calls the test function once for each peripheral
+ * of the given type.
+ */
 template<typename PortType, typename FormFactorType, typename PortType::TestFunctionType f>
 void all_peripherals()
 {
@@ -250,6 +272,17 @@ void all_peripherals()
     test_all_peripherals<PortType, typename PortType::TestFunctionType, f>(matched_ports, not_matched_ports);
 }
 
+/**
+ * Test function for one pinout of one peripheral of a given type
+ *
+ * This template function takes in three template parameters:
+ * - PortType - The type of peripheral to test
+ * - FormFactorType - The form factor to test on
+ * - f - The test function to run.
+ *
+ * This function is calls the test function once for one peripheral
+ * of the given type.
+ */
 template<typename PortType, typename FormFactorType, typename PortType::TestFunctionType f>
 void one_peripheral()
 {
@@ -358,6 +391,13 @@ bool operator== (const Port<N, PinMapType, FormFactorType, FunctionType> &port1,
     return true;
 }
 
+/**
+ * This is a convenience class for use with the above templates
+ *
+ * This class can be passed as a template parameter to all_ports,
+ * all_peripherals or one_peripheral to choose test pins from
+ * the default form factor.
+ */
 class DefaultFormFactor {
 public:
     static const PinList *pins()
@@ -376,6 +416,15 @@ public:
     }
 };
 
+/*
+ * Peripheral port declarations are given below
+ *
+ * Each Port type represents a set of pins used by a peripheral.
+ * The Port typedef is used as a template parameter to the functions
+ * all_ports, all_peripherals and one_peripheral to select the peripheral
+ * pin set to use for testing.
+ */
+
 #if DEVICE_SPI
 #include "spi_api.h"
 struct SPIMaps {