microbit: some work on tightening the API return codes.

still work in progress.

source/ManagedString.cpp

@@ -117,11 +117,11 @@ ManagedString::ManagedString(const ManagedString &s1, const ManagedString &s2)
   * character buffer may be declared on the stack for instance).
   *
   * @param str The character array on which to base the new ManagedString.
-  * @param length The length of the character array
+  * @param length The number of characters to use.
   *
   * Example:
   * @code 
-  * ManagedString s("abcdefg",7); // this is generally used for substring... why not use a normal char * constructor?
+  * ManagedString s("abcdefg",7); 
   * @endcode
   */  
 ManagedString::ManagedString(const char *str, const int16_t length)

source/MicroBit.cpp

@@ -261,11 +261,11 @@ void MicroBit::reset()
   * uBit.sleep(20); //sleep for 20ms
   * @endcode
   */
-void MicroBit::sleep(int milliseconds)
+int MicroBit::sleep(int milliseconds)
 {
     //sanity check, we can't time travel... (yet?)
     if(milliseconds < 0)
-        return;
+        return MICROBIT_INVALID_PARAMETER;
         
     if (flags & MICROBIT_FLAG_SCHEDULER_RUNNING)
         fiber_sleep(milliseconds);
@@ -296,7 +296,7 @@ int MicroBit::random(int max)
 {
     //return MICROBIT_INVALID_VALUE if max is <= 0...
     if(max <= 0)
-        return MICROBIT_INVALID_VALUE;
+        return MICROBIT_INVALID_PARAMETER;
     
     // Cycle the LFSR (Linear Feedback Shift Register).
     // We use an optimal sequence with a period of 2^32-1, as defined by Bruce Schneider here (a true legend in the field!),