Update api.md

Read() returns different data depending on how it's used.

Author: Phoenixxl

docs/api.md

@@ -571,7 +571,11 @@ file.read(buf, len)
 
 #### Returns
 
-The next byte (or character), or -1 if none is available.
+When used as `file.read()`
+The next byte (or character), or -1 if none is available. 
+
+When used as `file.read(buf, len)`
+The amount of bytes read, or -1 if an error occured.
 
 #### See also