Annotate README examples

Author: kemitchell

README.md

@@ -5,56 +5,27 @@ Give me a string and I'll tell you if it's a valid npm package license string.
 
 ```javascript
 var valid = require('validate-npm-package-license');
-var assert = require('assert');
+```
+
+SPDX license identifiers are valid license strings:
 
+```javascript
+
+var assert = require('assert');
 var validSPDXExpression = {
   validForNewPackages: true,
   validForOldPackages: true,
   spdx: true
 };
 
-// SPDX license identifier for common open-source licenses
 assert.deepEqual(valid('MIT'), validSPDXExpression);
 assert.deepEqual(valid('BSD-2-Clause'), validSPDXExpression);
 assert.deepEqual(valid('Apache-2.0'), validSPDXExpression);
 assert.deepEqual(valid('ISC'), validSPDXExpression);
+```
+The function will return a warning and suggestion for nearly-correct license identifiers:
 
-// Simple SPDX license expression for dual licensing
-assert.deepEqual(
-  valid('(GPL-3.0 OR BSD-2-Clause)'),
-  validSPDXExpression
-);
-
-// Refer to a non-standard license found in the package
-
-assert.deepEqual(
-  valid('SEE LICENSE IN LICENSE.txt'),
-  {
-    validForNewPackages: true,
-    validForOldPackages: true,
-    inFile: 'LICENSE.txt'
-  }
-);
-
-assert.deepEqual(
-  valid('SEE LICENSE IN license.md'),
-  {
-    validForNewPackages: true,
-    validForOldPackages: true,
-    inFile: 'license.md'
-  }
-);
-
-// No license
-var unlicensed = {
-  validForNewPackages: true,
-  validForOldPackages: true,
-  unlicensed: true
-};
-assert.deepEqual(valid('UNLICENSED'), unlicensed);
-assert.deepEqual(valid('UNLICENCED'), unlicensed);
-
-// Almost a valid SPDX license identifier
+```javascript
 assert.deepEqual(
   valid('Apache 2.0'),
   {
@@ -69,7 +40,21 @@ assert.deepEqual(
     ]
   }
 );
+```
+
+SPDX expressions are valid, too ...
+
+```javascript
+// Simple SPDX license expression for dual licensing
+assert.deepEqual(
+  valid('(GPL-3.0 OR BSD-2-Clause)'),
+  validSPDXExpression
+);
+```
+
+... except if they contain `LicenseRef`:
 
+```javascript
 var warningAboutLicenseRef = {
   validForOldPackages: false,
   validForNewPackages: false,
@@ -82,14 +67,47 @@ var warningAboutLicenseRef = {
   ]
 };
 
-// LicenseRef-* identifiers are valid SPDX expressions,
-// but not valid in package.json
 assert.deepEqual(
   valid('LicenseRef-Made-Up'),
   warningAboutLicenseRef
 );
+
 assert.deepEqual(
   valid('(MIT OR LicenseRef-Made-Up)'),
   warningAboutLicenseRef
 );
 ```
+
+If you can't describe your licensing terms with standardized SPDX identifiers, put the terms in a file in the package and point users there:
+
+```javascript
+assert.deepEqual(
+  valid('SEE LICENSE IN LICENSE.txt'),
+  {
+    validForNewPackages: true,
+    validForOldPackages: true,
+    inFile: 'LICENSE.txt'
+  }
+);
+
+assert.deepEqual(
+  valid('SEE LICENSE IN license.md'),
+  {
+    validForNewPackages: true,
+    validForOldPackages: true,
+    inFile: 'license.md'
+  }
+);
+```
+
+If there aren't any licensing terms, use `UNLICENSED`:
+
+```javascript
+var unlicensed = {
+  validForNewPackages: true,
+  validForOldPackages: true,
+  unlicensed: true
+};
+assert.deepEqual(valid('UNLICENSED'), unlicensed);
+assert.deepEqual(valid('UNLICENCED'), unlicensed);
+```