diff --git a/api/mraa/common.h b/api/mraa/common.h
index 9c75536..3dfcca7 100644
--- a/api/mraa/common.h
+++ b/api/mraa/common.h
@@ -48,7 +48,9 @@ typedef unsigned int mraa_boolean_t;
  *
  * Detects running platform and attempts to use included pinmap, this is run on
  * module/library init/load but is handy to rerun to check board initialised
- * correctly. Anything but MRAA_SUCCESS should be considered a critical failure
+ * correctly. MRAA_SUCCESS inidicates correct (first time) initialisation
+ * whilst MRAA_ERROR_PLATFORM_ALREADY_INITIALISED indicates the board is
+ * already initialised correctly
  *
  * @return Result of operation
  */
diff --git a/api/mraa/common.hpp b/api/mraa/common.hpp
index fb4bb40..14c00c1 100644
--- a/api/mraa/common.hpp
+++ b/api/mraa/common.hpp
@@ -44,7 +44,9 @@ namespace mraa {
  *
  * Detects running platform and attempts to use included pinmap, this is run on
  * module/library init/load but is handy to rerun to check board initialised
- * correctly. Anything but MRAA_SUCCESS should be considered a critical failure
+ * correctly. MRAA_SUCCESS inidicates correct (first time) initialisation
+ * whilst MRAA_ERROR_PLATFORM_ALREADY_INITIALISED indicates the board is
+ * already initialised correctly
  *
  * @return Result of operation
  */