add some JSDoc documentation

Author: kevb34ns

pinyinify.js

@@ -1,3 +1,17 @@
+/**
+ * @file Converts pinyin tone numbers to tone marks.
+ * @author Kevin K. Yang <[email protected]>
+ * @copyright Kevin K. Yang 2017. Licensed under the MIT License.
+ */
+
+/**
+ * An object holding arrays of Unicode tone marks for each vowel.
+ * Each tone mark can be accessed very intuitively. For example,
+ * to access the tone marked version of a2, you would call
+ * toneMarks["a"][2].
+ * 
+ * @type {Object}
+ */
 var toneMarks = {
    a: ["a", "\u0101", "\u00e1", "\u01ce", "\u00e0", "a"],
    e: ["e", "\u0113", "\u00e9", "\u011b", "\u00e8", "e"],
@@ -7,16 +21,29 @@ var toneMarks = {
    v: ["\u00fc", "\u01d6", "\u01d8", "\u01da", "\u01dc", "\u00fc"]
 };
 
+/**
+ * @return {Boolean} whether this string is a single alphabetical letter.
+ */
 String.prototype.isAlpha = function() {
 
    return /^[A-Za-z]$/.test(this);
 }
 
+/**
+ * @return {Boolean} is this string a valid pinyin vowel
+ */
 String.prototype.isPinyinVowel = function() {
 
    return /^[aeiouv\u00fc]$/.test(this);
 }
 
+/**
+ * Finds the last occurrence of a regular expression
+ * pattern match in this String.
+ * 
+ * @param  {RegExp} the pattern to match
+ * @return {Number} the last match in this string
+ */
 String.prototype.lastIndexOfRegex = function(regExp) {
 
    var lastIndex = -1;
@@ -31,6 +58,11 @@ String.prototype.lastIndexOfRegex = function(regExp) {
    return lastIndex;
 }
 
+/**
+ * @param  {Number} index The index of the character to replace
+ * @param  {String} replacement The string to insert at the index
+ * @return {String} this String, with the specified replacement
+ */
 String.prototype.replaceAt = function(index, replacement) {
 
    if (index >= 0 && index < this.length && typeof replacement === "string") {
@@ -44,34 +76,40 @@ String.prototype.replaceAt = function(index, replacement) {
 }
 
 /**
- * Takes a single pinyin word using tone numbers and converts to tone symbols.
+ * Converts this String, which must be a single pinyin word followed by a 
+ * tone number, to the equivalent pinyin word with tone marks.
+ * 
+ * @return {String} this String, with the tone number removed
+ *                       and tone mark inserted.
  */
 String.prototype.convertPinyin = function() {
-
+   // convert to lowercase
    var str = this.toLocaleLowerCase();
-
+   // get index of the tone number
    var toneNumIndex = str.search(/[1-5]/);
+   // get index of the first pinyin vowel
    var firstVowelIndex = str.search(/[aeiouv\u00fc]/);
    if (str.length > 7 || toneNumIndex < 1 || 
        toneNumIndex !== str.length - 1 ||
        firstVowelIndex < 0) {
-
+      // this string is either too long to be pinyin, does not contain a \
+      // correctly placed tone number, or has no pinyin vowels
       console.log("String.prototype.convertPinyin:" + this + 
                   " is not a valid pinyin word.")
       return this;
    }
-
+   /** @type {Number} from 1 to 5 */
    var toneNum = parseInt(str[toneNumIndex]);
    if (/[ae]/.test(str)) {
-
+      // str contains an 'a' or an 'e', both of which take precedence
       var index = str.search(/[ae]/);
       str = str.replaceAt(index, toneMarks[str.charAt(index)][toneNum]);
    } else if (/ou/.test(str)) {
-
+      // str contains 'ou'. The tone always goes on the 'o'
       var index = str.search(/ou/);
       str = str.replaceAt(index, toneMarks[str.charAt(index)][toneNum]);
    } else {
-
+      // place the tone on the last vowel
       var index = str.lastIndexOfRegex(/[aeiouv\u00fc]/);
       var vowel = str.charAt(index);
       if (vowel == "\u00fc") {
@@ -80,11 +118,15 @@ String.prototype.convertPinyin = function() {
       }
       str = str.replaceAt(index, toneMarks[vowel][toneNum]);
    }
-
+   // strip the tone number
    str = str.substring(0, str.length - 1);
    return str;
 }
 
+/**
+ * @param  {String} the string to convert
+ * @return {String} the converted string
+ */
 var pinyinify = function(str) {
 
    if (typeof str !== 'string') {
@@ -94,40 +136,46 @@ var pinyinify = function(str) {
 
    var res = "";
    var i = 0;
+   // parse str character by character
    while (str.length > 0) {
 
       var char = str.charAt(i);
       if (char.isAlpha()) {
-
+         // a letter has been found
          if (i !== 0) {
-
+            // remove non-letters found up to now, add to res
             res += str.substring(0, i);
             str = str.substring(i);
             i = 0;
          }
+         // get index of next tone number, if it exists
          var toneNumIndex = str.search(/[1-5]/);
+         // get index of next whitespace, if it exists
          var whitespaceIndex = str.search(/\s/);
+
          if (toneNumIndex > 0 && toneNumIndex < 7 &&
              (whitespaceIndex < 0 || whitespaceIndex > toneNumIndex)) {
-
+            // there is a tone number within 6 characters from now, and no \
+            // whitespaces between this character and the tone number
             res += str.substring(0, toneNumIndex + 1).convertPinyin();
             str = str.substring(toneNumIndex + 1);
          } else if (whitespaceIndex < 0) {
-
+            // no valid tone numbers nor whitespace, add rest of string to res
             res += str.substring(0);
             str = "";
          } else {
-
+            // whitespace found, remove everything up to and including the \
+            // whitespace, and add to res
             res += str.substring(0, whitespaceIndex + 1);
             str = str.substring(whitespaceIndex + 1);
          }
       } else if (i >= str.length) {
-
+         // no more characters to parse
          res += str.substring(0);
          str = "";
       }
       else {
-
+         // increment index
          i++;
       }
    }