Docs: Add jsdocs for human readable public methods (#1528)

Renamed parameters to be a little clearer, and marked them public since
they are being exported

Author: nschonni

lib/extensions.js

@@ -8,8 +8,17 @@ var eol = require('os').EOL,
     path = require('path'),
     defaultBinaryPath = path.join(__dirname, '..', 'vendor');
 
-function getHumanPlatform(arg) {
-  switch (arg || process.platform) {
+/**
+ * Get the human readable name of the Platform that is running
+ *
+ * @param  {string} platform - An OS platform to match, or null to fallback to
+ * the current process platform
+ * @return {Object} The name of the platform if matched, false otherwise
+ *
+ * @api public
+ */
+function getHumanPlatform(platform) {
+  switch (platform || process.platform) {
     case 'darwin': return 'OS X';
     case 'freebsd': return 'FreeBSD';
     case 'linux': return 'Linux';
@@ -18,17 +27,36 @@ function getHumanPlatform(arg) {
   }
 }
 
-function getHumanArchitecture(arg) {
-  switch (arg || process.arch) {
+/**
+ * Provides a more readable version of the architecture
+ *
+ * @param  {string} arch - An instruction architecture name to match, or null to
+ * lookup the current process architecture
+ * @return {Object} The value of the process architecture, or false if unknown
+ *
+ * @api public
+ */
+function getHumanArchitecture(arch) {
+  switch (arch || process.arch) {
     case 'ia32': return '32-bit';
     case 'x86': return '32-bit';
     case 'x64': return '64-bit';
     default: return false;
   }
 }
 
-function getHumanNodeVersion(arg) {
-  switch (parseInt(arg || process.versions.modules, 10)) {
+/**
+ * Get the friendly name of the Node environment being run
+ *
+ * @param  {Object} abi - A Node Application Binary Interface value, or null to
+ * fallback to the current Node ABI
+ * @return {Object} Returns a string name of the Node environment or false if
+ * unmatched
+ *
+ * @api public
+ */
+function getHumanNodeVersion(abi) {
+  switch (parseInt(abi || process.versions.modules, 10)) {
     case 11: return 'Node 0.10.x';
     case 14: return 'Node 0.12.x';
     case 42: return 'io.js 1.x';
@@ -42,6 +70,16 @@ function getHumanNodeVersion(arg) {
   }
 }
 
+/**
+ * Get a human readable description of where node-sass is running to support
+ * user error reporting when something goes wrong
+ *
+ * @param  {string} env - The name of the native bindings that is to be parsed
+ * @return {string} A description of what os, architecture, and Node version
+ * that is being run
+ *
+ * @api public
+ */
 function getHumanEnvironment(env) {
   var binding = env.replace(/_binding\.node$/, ''),
       parts = binding.split('-'),
@@ -70,15 +108,33 @@ function getHumanEnvironment(env) {
   ].join(' ');
 }
 
+/**
+ * Get the value of the binaries under the default path
+ *
+ * @return {Array} The currently installed node-sass bindings
+ *
+ * @api public
+ */
 function getInstalledBinaries() {
   return fs.readdirSync(defaultBinaryPath);
 }
 
-function isSupportedEnvironment(platform, arch, runtime) {
+/**
+ * Check that an environment matches the whitelisted values or the current
+ * environment if no parameters are passed
+ *
+ * @param  {string} platform - The name of the OS platform(darwin, win32, etc...)
+ * @param  {string} arch - The instruction set architecture of the Node environment
+ * @param  {string} abi - The Node Application Binary Interface
+ * @return {Boolean} True, if node-sass supports the current platform, false otherwise
+ *
+ * @api public
+ */
+function isSupportedEnvironment(platform, arch, abi) {
   return (
     false !== getHumanPlatform(platform) &&
     false !== getHumanArchitecture(arch) &&
-    false !== getHumanNodeVersion(runtime)
+    false !== getHumanNodeVersion(abi)
   );
 }