doc: Update docs for os.platform()

Author: hertzg

doc/api/os.markdown

@@ -24,7 +24,11 @@ Returns the operating system name.
 
 ## os.platform()
 
-Returns the operating system platform.
+Returns the operating system platform. Some of the possible values are `"linux"`, `"darwin"`, `"win32"`, `"sunos"` ...
+
+Its value is based on [`OS` constant of `gyp`](https://chromium.googlesource.com/external/gyp/+/HEAD/docs/InputFormatReference.md#Predefined-Variables), but with exceptions in case of Mac OS X, Windows and Solaris.
+
+On Windows its value is always `"win32"`, on Mac OS X its `"darwin"` and on Solaris its `"sunos"`.
 
 ## os.arch()