doc: update os.markdown

Some doc update based on improvement ideas I remember from when I used this module in node:

 - Mention windows returns 0 for `nice` values (which is obvious, but io makes no attempt to calculate something similar or return undefined, 0 is returned)
 - Mention platform and arch are aliases for `process` properties.
 - Document possible return values where appropriate, add examples in others.
 - Rename title in order to match other titles in the navigation.
 - Fix line that was over 80 characters long.

PR-URL: #976
Reviewed-By: Christian Tellnes <[email protected]>
Reviewed-By: Brian White <[email protected]>
Reviewed-By: Vladimir Kurchatkin <[email protected]>

Author: benjamingr

doc/api/os.markdown

@@ -1,4 +1,4 @@
-# os
+# OS
 
     Stability: 4 - API Frozen
 
@@ -8,28 +8,32 @@ Use `require('os')` to access this module.
 
 ## os.tmpdir()
 
-Returns the operating system's default directory for temp files.
+Returns the operating system's default directory for temporary files.
 
 ## os.endianness()
 
-Returns the endianness of the CPU. Possible values are `"BE"` or `"LE"`.
+Returns the endianness of the CPU. Possible values are `'BE'` for big endian
+or `'LE'` for little endian.
 
 ## os.hostname()
 
 Returns the hostname of the operating system.
 
 ## os.type()
 
-Returns the operating system name.
+Returns the operating system name. For example `'Linux'` on Linux, `'Darwin'`
+on OS X and `'Windows_NT'` on Windows.
 
 ## os.platform()
 
-Returns the operating system platform.
+Returns the operating system platform. Possible values are `'darwin'`,
+`'freebsd'`, `'linux'`, `'sunos'` or `'win32'`. Returns the value of
+`process.platform`.
 
 ## os.arch()
 
-Returns the operating system CPU architecture. Possible values are `"x64"`,
-`"arm"` and `"ia32"`.
+Returns the operating system CPU architecture. Possible values are `'x64'`,
+`'arm'` and `'ia32'`. Returns the value of `process.arch`.
 
 ## os.release()
 
@@ -132,6 +136,9 @@ Example inspection of os.cpus:
            idle: 1072572010,
            irq: 30 } } ]
 
+Note that since `nice` values are UNIX centric in Windows the `nice` values of
+all processors are always 0.
+
 ## os.networkInterfaces()
 
 Get a list of network interfaces:
@@ -164,4 +171,5 @@ interfaces that have been assigned an address.
 
 ## os.EOL
 
-A constant defining the appropriate End-of-line marker for the operating system.
+A constant defining the appropriate End-of-line marker for the operating
+system.