docs(*): add comments

docs/index.html

@@ -33,6 +33,16 @@ <h3 class='mb0 no-anchor'>wink-sentiment</h3>
 
                 </li>
 
+
+                <li><a
+                  href='#analyzesentiment'
+                  class="">
+                  analyzeSentiment
+
+                </a>
+
+                </li>
+
             </ul>
           </div>
           <div class='mt1 h6 quiet'>
@@ -81,6 +91,94 @@ <h3>Copyright &#x26; License</h3>
 </div>
 
 
+
+            <section class='p2 mb2 clearfix bg-white minishadow'>
+
+
+  <div class='clearfix'>
+
+    <h3 class='fl m0' id='analyzesentiment'>
+      analyzeSentiment
+    </h3>
+
+
+  </div>
+
+
+  <p>Computes the absolue  and normalized sentiment scores of the input <code>phrase</code>.
+The normalized score is computed by dividing the absolute score by the number
+of tokens; this is always between -5 and +5. A score of <strong>less than 0</strong> indicates
+negative sentiments and a score of <strong>more than 0</strong> indicates positive sentiments;
+wheras a <strong>near zero</strong> score suggests a neutral sentiment.</p>
+
+
+  <div class='pre p1 fill-light mt0'>analyzeSentiment(phrase: <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>): <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">object</a></div>
+
+
+
+
+
+
+
+
+
+
+
+    <div class='py1 quiet mt1 prose-big'>Parameters</div>
+    <div class='prose'>
+
+        <div class='space-bottom0'>
+          <div>
+            <span class='code bold'>phrase</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String">string</a>)</code>
+	    — whoes sentiment score needs to be computed.
+
+          </div>
+
+        </div>
+
+    </div>
+
+
+
+
+
+
+      <div class='py1 quiet mt1 prose-big'>Returns</div>
+      <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object">object</a></code>:
+        — absolute 
+<code>score</code>
+ and 
+<code>normalizedScore</code>
+ of 
+<code>phrase</code>
+.
+
+
+
+
+
+
+
+
+    <div class='py1 quiet mt1 prose-big'>Example</div>
+
+
+      <pre class='p1 overflow-auto round fill-light'>analyzeSentiment( <span class="hljs-string">'not a good product'</span> );
+<span class="hljs-comment">// -&gt; { score: -3, normalizedScore: -1 }</span>
+analyzeSentiment( <span class="hljs-string">'Excited to be part of the @imascientist team for the next couple of weeks!'</span> );
+<span class="hljs-comment">// { score: 3, normalizedScore: 0.21428571428571427 }</span></pre>
+
+
+
+
+
+
+
+
+</section>
+
+
+
       </div>
     </div>
   <script src='assets/anchor.js'></script>

src/wink-sentiment.js

@@ -40,7 +40,25 @@ var rgxEmojis = /([\uD800-\uDBFF][\uDC00-\uDFFF]|[\u2600-\u26FF]|[\u2700-\u27BF]
 // Used to expant elisions.
 var rgxNotElision = /([a-z])(n\'t)\b/gi;
 
-var analyze = function ( phrase ) {
+// ### analyzeSentiment
+/**
+ *
+ * Computes the absolue  and normalized sentiment scores of the input `phrase`.
+ * The normalized score is computed by dividing the absolute score by the number
+ * of tokens; this is always between -5 and +5. A score of **less than 0** indicates
+ * negative sentiments and a score of **more than 0** indicates positive sentiments;
+ * wheras a **near zero** score suggests a neutral sentiment.
+ *
+ * @param {string} phrase — whoes sentiment score needs to be computed.
+ * @return {object} — absolute `score` and `normalizedScore` of `phrase`.
+ *
+ * @example
+ * analyzeSentiment( 'not a good product' );
+ * // -> { score: -3, normalizedScore: -1 }
+ * analyzeSentiment( 'Excited to be part of the @imascientist team for the next couple of weeks!' );
+ * // { score: 3, normalizedScore: 0.21428571428571427 }
+ */
+var analyzeSentiment = function ( phrase ) {
   if ( typeof phrase !== 'string' ) {
     throw Error( 'wink-sentiment: input phrase must be a string, instead found: ' + typeof phrase );
   }
@@ -110,6 +128,6 @@ var analyze = function ( phrase ) {
   // if ( words === 0 ) words = 1;
   // Return score and its normalized value.
   return { score: ss, normalizedScore: ( ss / words ) };
-};
+}; // analyzeSentiment()
 
-module.exports = analyze;
+module.exports = analyzeSentiment;

test/wink-sentiment-specs.js

@@ -24,6 +24,10 @@ describe( 'basic test cycle', function () {
     expect( ws( 'not a good product' ) ).to.deep.equal( { score: -3, normalizedScore: -1 } );
   } );
 
+  it( 'should return a score of 3/1.5 with "not a good product"', function () {
+    expect( ws( 'good product' ) ).to.deep.equal( { score: 3, normalizedScore: 1.5 } );
+  } );
+
   it( 'should return a score of -2/-1 with "bad luck"', function () {
     expect( ws( 'bad luck' ) ).to.deep.equal( { score: -2, normalizedScore: -1 } );
   } );