Merge pull request #8410 from cmonr/rollup-aus_writathon

Rollup: Austin Writathon + a few more docs PRs

Author: Cruz Monrreal

.github/issue_template.md

@@ -1,5 +1,6 @@
 ### Description
-<!-- 
+
+<!--
     Required
     Add detailed description of what you are reporting.
     Good example: https://os.mbed.com/docs/latest/reference/workflow.html
@@ -13,19 +14,15 @@
 
 
 ### Issue request type
-<!-- 
-    Required
-    Please add only one X to one of the following types. Do not fill multiple types. (Split the issue otherwise.)
-    Please note this is not a GitHub task list; indenting the boxes or changing the format to add a '.' or '*' in front
-    of them changes the meaning incorrectly. The only changes to make are to add a description under the
-    description heading and to add an 'x' to the correct box.
 
-    [X] Question
-    [ ] Enhancement 
-    [ ] Bug 
+<!--
+    Required
+    Please add only one X to one of the following types. Do not fill multiple types (split the issue otherwise.)
+    Please note this is not a GitHub task list, indenting the boxes or changing the format to add a '.' or '*' in front
+    of them would change the meaning incorrectly. The only changes to be made are to add a description text under the
+    description heading and to add a 'x' to the correct box.
 -->
-
-[ ] Question  
-[ ] Enhancement  
-[ ] Bug  
+    [ ] Question
+    [ ] Enhancement
+    [ ] Bug
 

UNITTESTS/README.md

@@ -1,6 +1,6 @@
 ## Unit testing
 
-This document describes how to write and test unit tests for Mbed OS. To prevent and solve problems, please see the [troubleshooting](#troubleshooting) section.
+This document describes how to write and test unit tests for Arm Mbed OS. To prevent and solve problems, please see the [troubleshooting](#troubleshooting) section.
 
 ### Introduction
 
@@ -16,7 +16,7 @@ Please install the following dependencies to use Mbed OS unit testing.
 - Python 2.7.x, 3.5 or newer.
 - Pip 10.0 or newer.
 - Gcovr 4.1 or newer.
-- Mbed CLI 1.8.0 or newer.
+- Arm Mbed CLI 1.8.0 or newer.
 
 Detailed instructions for supported operating systems are below.
 
@@ -30,7 +30,7 @@ Detailed instructions for supported operating systems are below.
    sudo easy_install pip
    ```
 
-1. Install Gcovr and [Mbed CLI](https://os.mbed.com/docs/latest/tools/arm-mbed-cli.html) with `pip install "gcovr>=4.1" mbed-cli`.
+1. Install Gcovr and [Mbed CLI](https://os.mbed.com/docs/latest/tools/developing-arm-mbed-cli.html) with `pip install "gcovr>=4.1" mbed-cli`.
 
 #### Installing dependencies on macOS
 
@@ -43,15 +43,15 @@ Detailed instructions for supported operating systems are below.
    sudo easy_install pip
    ```
 
-1. Install Gcovr and [Mbed CLI](https://os.mbed.com/docs/latest/tools/arm-mbed-cli.html) with `pip install "gcovr>=4.1" mbed-cli`.
+1. Install Gcovr and [Mbed CLI](https://os.mbed.com/docs/latest/tools/developing-arm-mbed-cli.html) with `pip install "gcovr>=4.1" mbed-cli`.
 
 #### Installing dependencies on Windows
 
 1. Download and install [MinGW-W64](http://mingw-w64.org/).
 1. Download CMake binaries from https://cmake.org/download/, and run the installer.
 1. Download Python 2.7 or Python 3 from https://www.python.org/getit/, and run the installer.
 1. Add MinGW, CMake and Python into system PATH.
-1. Install Gcovr and [Mbed CLI](https://os.mbed.com/docs/latest/tools/arm-mbed-cli.html) with `pip install "gcovr>=4.1" mbed-cli`.
+1. Install Gcovr and [Mbed CLI](https://os.mbed.com/docs/latest/tools/developing-arm-mbed-cli.html) with `pip install "gcovr>=4.1" mbed-cli`.
 
 ### Test code structure
 
@@ -69,7 +69,7 @@ The build system automatically generates names of test suites. The name is const
 
 ### Unit testing with Mbed CLI
 
-Mbed CLI supports unit tests through `mbed test --unittests` command. For information on using Mbed CLI, please see the [CLI documentation in handbook](https://os.mbed.com/docs/latest/tools/arm-mbed-cli.html).
+Mbed CLI supports unit tests through `mbed test --unittests` command. For information on using Mbed CLI, please see the [CLI documentation](https://os.mbed.com/docs/latest/tools/developing-arm-mbed-cli.html).
 
 ### Writing unit tests
 
@@ -154,17 +154,19 @@ TEST_F(TestSemaphore, constructor)
 
 ### Building and running unit tests
 
-Use Mbed CLI to build and run unit tests. For advanced use, you can run CMake and a make program directly.
+Use Mbed CLI to build and run unit tests. For advanced use, you can run CMake and a Make program directly.
 
 #### Build tests directly with CMake
 
 1. Create a build directory `mkdir UNITTESTS/build`.
 1. Move to the build directory `cd UNITTESTS/build`.
 1. Run CMake using a relative path to `UNITTESTS` folder as the argument. So from `UNITTESTS/build` use `cmake ..`:
    - Add `-g [generator]` if generating other than Unix Makefiles such in case of MinGW use `-g "MinGW Makefiles"`.
-   - Add `-DCOVERAGE:True` to add coverage compiler flags.
+   - Add `-DCMAKE_MAKE_PROGRAM=<value>`, `-DCMAKE_CXX_COMPILER=<value>` and `-DCMAKE_C_COMPILER=<value>` to use a specific Make program and compilers.
+   - Add `-DCMAKE_BUILD_TYPE=Debug` to build a debug build.
+   - Add `-DCOVERAGE=True` to add coverage compiler flags.
    - See the [CMake manual](https://cmake.org/cmake/help/v3.0/manual/cmake.1.html) for more information.
-1. Run a make program (Make, Gmake, Mingw32-make and so on) to build the tests.
+1. Run a Make program to build the tests.
 
 #### Run tests directly with CTest
 
@@ -177,14 +179,24 @@ Run a test binary in the build directory to run a unit test suite. To run multip
 1. Add test executables into the list.
 1. Run them.
 
+### Debugging
+
+1. Use Mbed CLI to build a debug build. For advanced use, run CMake directly with `-DCMAKE_BUILD_TYPE=Debug`, and then run a Make program.
+1. Run GDB with a test executable as an argument to debug unit tests.
+
 ### Get code coverage
 
-Use Mbed CLI to generate code coverage reports. For advanced use, you can run Gcovr or any other code coverage tool directly in the build directory.
+Use Mbed CLI to generate code coverage reports. For advanced use, follow these steps:
+
+1. Run CMake with both `-DCMAKE_BUILD_TYPE=Debug` and `-DCOVERAGE=True`.
+1. Run a Make program to build the tests.
+1. Run the tests.
+1. Run Gcovr or any other code coverage tool directly in the build directory.
 
 ### Troubleshooting
 
 **Problem:** Generic problems with CMake or with the build process.
-* **Solution**: Delete the build directory. Make sure that CMake, g++, gcc and a make program can be found in the path and are correct versions.
+* **Solution**: Delete the build directory. Make sure that CMake, g++, GCC and a Make program can be found in the path and are correct versions.
 
 **Problem:** Virus protection identifies files generated by CMake as malicious and quarantines the files on Windows.
 * **Solution**: Restore the false positive files from the quarantine.

drivers/CAN.h

@@ -85,7 +85,7 @@ class CANMessage : public CAN_Message {
 class CAN : private NonCopyable<CAN> {
 
 public:
-    /** Creates an CAN interface connected to specific pins.
+    /** Creates a CAN interface connected to specific pins.
      *
      *  @param rd read from transmitter
      *  @param td transmit to transmitter
@@ -94,11 +94,14 @@ class CAN : private NonCopyable<CAN> {
      * @code
      * #include "mbed.h"
      *
+     *
      * Ticker ticker;
      * DigitalOut led1(LED1);
      * DigitalOut led2(LED2);
-     * CAN can1(p9, p10);
-     * CAN can2(p30, p29);
+     * //The constructor takes in RX, and TX pin respectively.
+     * //These pins, for this example, are defined in mbed_app.json
+     * CAN can1(MBED_CONF_APP_CAN1_RD, MBED_CONF_APP_CAN1_TD);
+     * CAN can2(MBED_CONF_APP_CAN2_RD, MBED_CONF_APP_CAN2_TD);
      *
      * char counter = 0;
      *
@@ -121,14 +124,15 @@ class CAN : private NonCopyable<CAN> {
      *         wait(0.2);
      *     }
      * }
+     * 
      * @endcode
      */
     CAN(PinName rd, PinName td);
 
     /** Initialize CAN interface and set the frequency
       *
-      * @param rd the rd pin
-      * @param td the td pin
+      * @param rd the read pin
+      * @param td the transmit pin
       * @param hz the bus frequency in hertz
       */
     CAN(PinName rd, PinName td, int hz);
@@ -288,12 +292,14 @@ class CAN : private NonCopyable<CAN> {
 
     static void _irq_handler(uint32_t id, CanIrqType type);
 
+#if !defined(DOXYGEN_ONLY)
 protected:
     virtual void lock();
     virtual void unlock();
     can_t               _can;
     Callback<void()>    _irq[IrqCnt];
     PlatformMutex       _mutex;
+#endif
 };
 
 } // namespace mbed

drivers/InterruptIn.h

@@ -48,6 +48,7 @@ namespace mbed {
  * }
  *
  * int main() {
+ *     // register trigger() to be called upon the rising edge of event
  *     event.rise(&trigger);
  *     while(1) {
  *         led = !led;
@@ -71,7 +72,10 @@ class InterruptIn : private NonCopyable<InterruptIn> {
      *  and the pin configured to the specified mode.
      *
      *  @param pin InterruptIn pin to connect to
-     *  @param mode The mode to set the pin to (PullUp/PullDown/etc.)
+     *  @param mode Desired Pin mode configuration.
+     *  (Valid values could be PullNone, PullDown, PullUp and PullDefault.
+     *  See PinNames.h for your target for definitions)
+     *
      */
     InterruptIn(PinName pin, PinMode mode);
 
@@ -142,11 +146,12 @@ class InterruptIn : private NonCopyable<InterruptIn> {
 
     /** Set the input pin mode
      *
-     *  @param pull PullUp, PullDown, PullNone
+     *  @param pull PullUp, PullDown, PullNone, PullDefault
+     *  See PinNames.h for your target for definitions)
      */
     void mode(PinMode pull);
 
-    /** Enable IRQ. This method depends on hw implementation, might enable one
+    /** Enable IRQ. This method depends on hardware implementation, might enable one
      *  port interrupts. For further information, check gpio_irq_enable().
      */
     void enable_irq();
@@ -157,7 +162,7 @@ class InterruptIn : private NonCopyable<InterruptIn> {
     void disable_irq();
 
     static void _irq_handler(uint32_t id, gpio_irq_event event);
-
+#if !defined(DOXYGEN_ONLY)
 protected:
     gpio_t gpio;
     gpio_irq_t gpio_irq;
@@ -166,6 +171,7 @@ class InterruptIn : private NonCopyable<InterruptIn> {
     Callback<void()> _fall;
 
     void irq_init(PinName pin);
+#endif
 };
 
 } // namespace mbed

drivers/QSPI.h

@@ -84,19 +84,22 @@ class QSPI : private NonCopyable<QSPI> {
      *  @param io3 4th IO pin used for sending/receiving data during data phase of a transaction
      *  @param sclk QSPI Clock pin
      *  @param ssel QSPI chip select pin
-     *  @param mode Mode specifies the SPI mode(Mode=0 uses CPOL=0, CPHA=0, Mode=1 uses CPOL=1, CPHA=1)
-     *         default value = 0
+     *  @param mode Clock polarity and phase mode (0 - 3) of SPI
+     *         (Default: Mode=0 uses CPOL=0, CPHA=0, Mode=1 uses CPOL=1, CPHA=1)
      *
      */
     QSPI(PinName io0, PinName io1, PinName io2, PinName io3, PinName sclk, PinName ssel = NC, int mode = 0);
+    virtual ~QSPI()
+    {
+    }
 
     /** Configure the data transmission format
      *
      *  @param inst_width Bus width used by instruction phase(Valid values are QSPI_CFG_BUS_SINGLE, QSPI_CFG_BUS_DUAL, QSPI_CFG_BUS_QUAD)
      *  @param address_width Bus width used by address phase(Valid values are QSPI_CFG_BUS_SINGLE, QSPI_CFG_BUS_DUAL, QSPI_CFG_BUS_QUAD)
      *  @param address_size Size in bits used by address phase(Valid values are QSPI_CFG_ADDR_SIZE_8, QSPI_CFG_ADDR_SIZE_16, QSPI_CFG_ADDR_SIZE_24, QSPI_CFG_ADDR_SIZE_32)
      *  @param alt_width Bus width used by alt phase(Valid values are QSPI_CFG_BUS_SINGLE, QSPI_CFG_BUS_DUAL, QSPI_CFG_BUS_QUAD)
-     *  @param alt_size Size in bits used by alt phase(Valid values are QSPI_CFG_ADDR_SIZE_8, QSPI_CFG_ADDR_SIZE_16, QSPI_CFG_ADDR_SIZE_24, QSPI_CFG_ADDR_SIZE_32)
+     *  @param alt_size Size in bits used by alt phase(Valid values are QSPI_CFG_ALT_SIZE_8, QSPI_CFG_ALT_SIZE_16, QSPI_CFG_ALT_SIZE_24, QSPI_CFG_ALT_SIZE_32)
      *  @param data_width Bus width used by data phase(Valid values are QSPI_CFG_BUS_SINGLE, QSPI_CFG_BUS_DUAL, QSPI_CFG_BUS_QUAD)
      *  @param dummy_cycles Number of dummy clock cycles to be used after alt phase
      *
@@ -179,6 +182,7 @@ class QSPI : private NonCopyable<QSPI> {
      */
     qspi_status_t command_transfer(int instruction, int address, const char *tx_buffer, size_t tx_length, const char *rx_buffer, size_t rx_length);
 
+#if !defined(DOXYGEN_ONLY)
 protected:
     /** Acquire exclusive access to this SPI bus
      */
@@ -188,12 +192,6 @@ class QSPI : private NonCopyable<QSPI> {
      */
     virtual void unlock(void);
 
-public:
-    virtual ~QSPI()
-    {
-    }
-
-protected:
     qspi_t _qspi;
 
     bool acquire(void);
@@ -223,6 +221,7 @@ class QSPI : private NonCopyable<QSPI> {
      * This function builds the qspi command struct to be send to Hal
      */
     inline void _build_qspi_command(int instruction, int address, int alt);
+#endif
 };
 
 } // namespace mbed

drivers/Ticker.h

@@ -35,7 +35,7 @@ namespace mbed {
  *
  * Example:
  * @code
- * // Toggle the blinking led after 5 seconds
+ * // Toggle the blinking LED after 5 seconds
  *
  * #include "mbed.h"
  *
@@ -70,7 +70,7 @@ class Ticker : public TimerEvent, private NonCopyable<Ticker> {
     {
     }
 
-    // When low power ticker is in use, then do not disable deep-sleep.
+    // When low power ticker is in use, then do not disable deep sleep.
     Ticker(const ticker_data_t *data) : TimerEvent(data), _function(0), _lock_deepsleep(true)
     {
 #if DEVICE_LPTICKER
@@ -106,13 +106,13 @@ class Ticker : public TimerEvent, private NonCopyable<Ticker> {
         attach(callback(obj, method), t);
     }
 
-    /** Attach a function to be called by the Ticker, specifying the interval in micro-seconds
+    /** Attach a function to be called by the Ticker, specifying the interval in microseconds
      *
      *  @param func pointer to the function to be called
      *  @param t the time between calls in micro-seconds
      *
-     *  @note setting @a t to a value shorter that it takes to process the ticker callback
-     *  will cause the system to hang. Ticker callback will be called constantly with no time
+     *  @note setting @a t to a value shorter than it takes to process the ticker callback
+     *  causes the system to hang. Ticker callback is called constantly with no time
      *  for threads scheduling.
      *
      */
@@ -128,11 +128,11 @@ class Ticker : public TimerEvent, private NonCopyable<Ticker> {
         core_util_critical_section_exit();
     }
 
-    /** Attach a member function to be called by the Ticker, specifying the interval in micro-seconds
+    /** Attach a member function to be called by the Ticker, specifying the interval in microseconds
      *
      *  @param obj pointer to the object to call the member function on
      *  @param method pointer to the member function to be called
-     *  @param t the time between calls in micro-seconds
+     *  @param t the time between calls in microseconds
      *  @deprecated
      *      The attach_us function does not support cv-qualifiers. Replaced by
      *      attach_us(callback(obj, method), t).
@@ -155,14 +155,16 @@ class Ticker : public TimerEvent, private NonCopyable<Ticker> {
      */
     void detach();
 
+#if !defined(DOXYGEN_ONLY)
 protected:
     void setup(us_timestamp_t t);
     virtual void handler();
 
 protected:
-    us_timestamp_t         _delay;  /**< Time delay (in microseconds) for re-setting the multi-shot callback. */
+    us_timestamp_t         _delay;  /**< Time delay (in microseconds) for resetting the multishot callback. */
     Callback<void()>    _function;  /**< Callback. */
-    bool          _lock_deepsleep;  /**< Flag which indicates if deep-sleep should be disabled. */
+    bool          _lock_deepsleep;  /**< Flag which indicates if deep sleep should be disabled. */
+#endif
 };
 
 } // namespace mbed

drivers/Timeout.h

@@ -25,7 +25,7 @@ namespace mbed {
 
 /** A Timeout is used to call a function at a point in the future
  *
- * You can use as many seperate Timeout objects as you require.
+ * You can use as many separate Timeout objects as you require.
  *
  * @note Synchronization level: Interrupt safe
  *