Merge pull request #8475 from cmonr/rollup

Rollup PR

Author: Cruz Monrreal

UNITTESTS/README.md

@@ -11,7 +11,7 @@ Unit tests test code in small sections on a host machine. Unlike other testing t
 Please install the following dependencies to use Mbed OS unit testing. 
 
 - GNU toolchains.
-   - GCC 6 or later. We recommend you use MinGW-W64 on Windows, but any Windows port of the above GCC versions works.
+   - GCC 6 or later. We recommend you use MinGW-W64 on Windows, but any Windows port of the above GCC versions works. Default compilers can be used on Mac OS instead of GCC to shorten build times, but code coverage results can then differ.
 - CMake 3.0 or newer.
 - Python 2.7.x, 3.5 or newer.
 - Pip 10.0 or newer.
@@ -35,7 +35,8 @@ Detailed instructions for supported operating systems are below.
 #### Installing dependencies on macOS
 
 1. Install [Homebrew](https://brew.sh/).
-1. Install GCC compilers and CMake with: `brew install gcc cmake`.
+1. Install Xcode Command Line Tools with `xcode-select --install`.
+1. Install CMake with: `brew install cmake`.
 1. Install Python and Pip:
 
    ```
@@ -44,6 +45,7 @@ Detailed instructions for supported operating systems are below.
    ```
 
 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`.
+1. (Optional) Install GCC with `brew install gcc`.
 
 #### Installing dependencies on Windows
 
@@ -200,3 +202,6 @@ Use Mbed CLI to generate code coverage reports. For advanced use, follow these s
 
 **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.
+
+**Problem:** CMake compiler check fails on Mac OS Mojave when using GCC-8.
+* **Solution**: Make sure gnm (binutils) is not installed. Uninstall binutils with `brew uninstall binutils`.

drivers/PwmOut.h

@@ -32,7 +32,7 @@ namespace mbed {
  *
  * Example
  * @code
- * // Fade a led on.
+ * // Gradually change the intensity of the LED.
  * #include "mbed.h"
  *
  * PwmOut led(LED1);
@@ -118,8 +118,8 @@ class PwmOut {
         core_util_critical_section_exit();
     }
 
-    /** Set the PWM period, specified in milli-seconds (int), keeping the duty cycle the same.
-     *  @param ms Change the period of a PWM signal in milli-seconds without modifying the duty cycle
+    /** Set the PWM period, specified in milliseconds (int), keeping the duty cycle the same.
+     *  @param ms Change the period of a PWM signal in milliseconds without modifying the duty cycle
      */
     void period_ms(int ms)
     {
@@ -128,8 +128,8 @@ class PwmOut {
         core_util_critical_section_exit();
     }
 
-    /** Set the PWM period, specified in micro-seconds (int), keeping the duty cycle the same.
-     *  @param us Change the period of a PWM signal in micro-seconds without modifying the duty cycle
+    /** Set the PWM period, specified in microseconds (int), keeping the duty cycle the same.
+     *  @param us Change the period of a PWM signal in microseconds without modifying the duty cycle
      */
     void period_us(int us)
     {
@@ -148,8 +148,8 @@ class PwmOut {
         core_util_critical_section_exit();
     }
 
-    /** Set the PWM pulsewidth, specified in milli-seconds (int), keeping the period the same.
-     *  @param ms Change the pulse width of a PWM signal specified in milli-seconds
+    /** Set the PWM pulsewidth, specified in milliseconds (int), keeping the period the same.
+     *  @param ms Change the pulse width of a PWM signal specified in milliseconds
      */
     void pulsewidth_ms(int ms)
     {
@@ -158,8 +158,8 @@ class PwmOut {
         core_util_critical_section_exit();
     }
 
-    /** Set the PWM pulsewidth, specified in micro-seconds (int), keeping the period the same.
-     *  @param us Change the pulse width of a PWM signal specified in micro-seconds
+    /** Set the PWM pulsewidth, specified in microseconds (int), keeping the period the same.
+     *  @param us Change the pulse width of a PWM signal specified in microseconds
      */
     void pulsewidth_us(int us)
     {
@@ -197,6 +197,7 @@ class PwmOut {
         return read();
     }
 
+#if !(DOXYGEN_ONLY)
 protected:
     /** Lock deep sleep only if it is not yet locked */
     void lock_deep_sleep()
@@ -219,6 +220,7 @@ class PwmOut {
     pwmout_t _pwm;
     bool _deep_sleep_locked;
 };
+#endif
 
 } // namespace mbed
 

drivers/RawSerial.h

@@ -88,6 +88,7 @@ class RawSerial: public SerialBase, private NonCopyable<RawSerial> {
 
     int printf(const char *format, ...);
 
+#if !(DOXYGEN_ONLY)
 protected:
 
     /* Acquire exclusive access to this serial port
@@ -97,6 +98,7 @@ class RawSerial: public SerialBase, private NonCopyable<RawSerial> {
     /* Release exclusive access to this serial port
      */
     virtual void unlock(void);
+#endif
 };
 
 } // namespace mbed

drivers/Serial.h

@@ -63,10 +63,10 @@ class Serial : public SerialBase, public Stream, private NonCopyable<Serial> {
      *  @param tx Transmit pin
      *  @param rx Receive pin
      *  @param name The name of the stream associated with this serial port (optional)
-     *  @param baud The baud rate of the serial port (optional, defaults to MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE)
+     *  @param baud The baud rate of the serial port (optional, defaults to MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE or 9600)
      *
      *  @note
-     *    Either tx or rx may be specified as NC if unused
+     *    Either tx or rx may be specified as NC (Not Connected) if unused
      */
     Serial(PinName tx, PinName rx, const char *name = NULL, int baud = MBED_CONF_PLATFORM_DEFAULT_SERIAL_BAUD_RATE);
 
@@ -78,7 +78,7 @@ class Serial : public SerialBase, public Stream, private NonCopyable<Serial> {
      *  @param baud The baud rate of the serial port
      *
      *  @note
-     *    Either tx or rx may be specified as NC if unused
+     *    Either tx or rx may be specified as NC (Not Connected) if unused
      */
     Serial(PinName tx, PinName rx, int baud);
 
@@ -99,13 +99,15 @@ class Serial : public SerialBase, public Stream, private NonCopyable<Serial> {
         return SerialBase::writeable();
     }
 
+#if !(DOXYGEN_ONLY)
 protected:
     virtual int _getc();
     virtual int _putc(int c);
     virtual void lock();
     virtual void unlock();
 
     PlatformMutex _mutex;
+#endif
 };
 
 } // namespace mbed

events/mbed_shared_queues.h

@@ -75,7 +75,7 @@ events::EventQueue *mbed_event_queue();
  * @note
  * mbed_highprio_event_queue is not itself IRQ safe. To use the
  * mbed_highprio_event_queue in interrupt context, you must first call
- * `mbed_event_queue()` in threaded context and store the pointer for
+ * `mbed_highprio_event_queue()` in threaded context and store the pointer for
  * later use.
  *
  * @return pointer to high-priority event queue

platform/DirHandle.h

@@ -30,18 +30,24 @@ namespace mbed {
  */
 
 
-/** Represents a directory stream. Objects of this type are returned
- *  by an opendir function. The core functions are read and seek,
+/** Represents a directory stream. An opendir function returns 
+ *  objects of this type. The core functions are read and seek,
  *  but only a subset needs to be provided.
  *
- *  If a FileSystemLike class defines the opendir method, then the
- *  directories of an object of that type can be accessed by
- *  DIR *d = opendir("/example/directory") (or opendir("/example")
- *  to open the root of the filesystem), and then using readdir(d) etc.
+ *  If a FileSystemLike class defines the opendir method, then you
+ *  can access the directories of an object of that type by either:
+ *  @code
+ *  DIR *d  = opendir("/example/directory");
+ *  @endcode
+ *  or
+ *  @code
+ *  DIR *d = opendir("/example");
+ *  @endcode
+ *  to open the root of the file system.
  *
  *  The root directory is considered to contain all FileHandle and
- *  FileSystem objects, so the DIR* returned by opendir("/") will
- *  reflect this.
+ *  FileSystem objects, so the DIR pointer returned by opendir("/")
+ *  reflects this.
  *
  *  @note to create a directory, @see Dir
  *  @note Synchronization level: Set by subclass
@@ -113,7 +119,7 @@ class DirHandle : private NonCopyable<DirHandle> {
         return close();
     };
 
-    /** Return the directory entry at the current position, and
+    /** Returns the directory entry at the current position, and
      *  advances the position to the next entry.
      *
      * @returns