PlatformMutex docs update

Author: Filip Jagodzinski

platform/PlatformMutex.h

@@ -1,10 +1,3 @@
-
-/** \addtogroup platform */
-/** @{*/
-/**
- * \defgroup platform_PlatformMutex PlatformMutex class
- * @{
- */
 /* mbed Microcontroller Library
  * Copyright (c) 2006-2013 ARM Limited
  *
@@ -25,32 +18,67 @@
 
 #include "platform/NonCopyable.h"
 
+/** \addtogroup platform
+ * @{
+ */
+
+/** \defgroup platform_PlatformMutex PlatformMutex class
+ * @{
+ */
+
+/** The PlatformMutex class is used to synchronize the execution of threads.
+ *
+ * The PlatformMutex class is used by Mbed OS drivers instead of rtos::Mutex.
+ * This enables the use of drivers when the Mbed OS is compiled without the RTOS.
+ *
+ * @note
+ * - When the RTOS is present, the PlatformMutex becomes a typedef for rtos::Mutex.
+ * - When the RTOS is absent, all methods are defined as noop.
+ */
+
 #ifdef MBED_CONF_RTOS_PRESENT
+
 #include "rtos/Mutex.h"
 typedef rtos::Mutex PlatformMutex;
+
 #else
-/** A stub mutex for when an RTOS is not present
-*/
-class PlatformMutex : private mbed::NonCopyable<PlatformMutex> {
+
+class PlatformMutex: private mbed::NonCopyable<PlatformMutex> {
 public:
+    /** Create a PlatformMutex object.
+     *
+     * @note When the RTOS is present, this is an alias for rtos::Mutex::Mutex().
+     */
     PlatformMutex()
     {
-        // Stub
-
     }
+
+    /** PlatformMutex destructor.
+     *
+     * @note When the RTOS is present, this is an alias for rtos::Mutex::~Mutex().
+     */
     ~PlatformMutex()
     {
-        // Stub
     }
 
+    /** Wait until a PlatformMutex becomes available.
+     *
+     * @note
+     * - When the RTOS is present, this is an alias for rtos::Mutex::lock().
+     * - When the RTOS is absent, this is a noop.
+     */
     void lock()
     {
-        // Do nothing
     }
 
+    /** Unlock a PlatformMutex that has previously been locked by the same thread.
+     *
+     * @note
+     * - When the RTOS is present, this is an alias for rtos::Mutex::unlock().
+     * - When the RTOS is absent, this is a noop.
+     */
     void unlock()
     {
-        // Do nothing
     }
 };