Add JSDoc comments to the public interface

1 files changed, 157 insertions, 0 deletions

diff --git a/south-african-id-parser.js b/south-african-id-parser.js
index 8e233e7..73450ea 100644
--- a/south-african-id-parser.js
+++ b/south-african-id-parser.js
@@ -11,12 +11,169 @@
 }(this, function () {
   'use strict';
 
+  /**
+   * Parsing result for a valid South African ID number.
+   *
+   * @typedef {Object} ValidIDParseResult
+   * @property {bool} isValid - true
+   * @property {Date} dateOfBirth - The date of birth from the ID number.
+   * @property {bool} isMale - The sex from the ID number - true if male, false if female.
+   * @property {bool} isFemale - The sex from the ID number - true if female, false if male.
+   * @property {bool} isSouthAfricanCitizen - Citizenship status from the ID
+   *   number, true if it indicates South African citizenship.
+   */
+
+  /**
+   * Parsing result for a invalid South African ID number.
+   *
+   * @typedef {Object} InvalidIDParseResult
+   * @property {bool} isValid - false
+   */
+
   return {
+    /**
+     * Validates and ID number and parses out all information from it.
+     *
+     * This is a combination of the other parsing and validation functions, so
+     * refer to their documentation for any details.
+     *
+     * @function
+     * @param {string} idNumber - The ID number to be parsed.
+     * @return {ValidIDParseResult|InvalidIDParseResult} An object with all of
+     *   the parsing results. If the ID is invalid, the result is an object with
+     *   just an `isValid` property set to false.
+     *
+     * @example
+     * var saIdParser = require('south-african-id-parser');
+     * var validIdNumber = '9001049818080';
+     *
+     * var info = saIdParser.parse(validIdNumber);
+     * // info === {
+     * //   isValid: true,
+     * //   dateOfBirth: new Date(1990, 01, 04),
+     * //   isMale: true,
+     * //   isFemale: false,
+     * //   isSouthAfricanCitizen: true
+     * // }
+     *
+     * var invalidIdNumber = '1234567';
+     * info = saIdParser.parse(invalidIdNumber);
+     * // info === {
+     * //   isValid: false
+     * // }
+     */
     parse: parse,
+
+    /**
+     * Validates an ID number.
+     *
+     * This includes making sure that it follows the expected 13 digit pattern,
+     * checking that the control digit is correct, and checking that the date of
+     * birth is a valid date.
+     *
+     * @function
+     * @param {string} idNumber - The ID number to be validated.
+     * @return {bool} True if the ID number is a valid South African ID number.
+     *
+     * @example
+     * var saIdParser = require('south-african-id-parser');
+     * var validIdNumber = '9001049818080';
+     * var isValid = saIdParser.validate(validIdNumber);
+     *
+     * // valid === true
+     */
     validate: validate,
+
+    /**
+     * Parses the date of birth out of an ID number.
+     *
+     * Minimal validation of the ID number is performed, requiring only that
+     * it's 13 digits long.
+     *
+     * The date of birth included in the ID number has a two digit year. For
+     * example, 90 instead of 1990. This is converted to a full date by
+     * comparing the date of birth to the current date, and choosing the century
+     * that gives the person the lowest age, while still putting their age in
+     * the past.
+     *
+     * For example, assuming that the current date is 10 December 2015. If the
+     * date of birth parsed is 10 December 15, it will be interpreted as 10
+     * December 2015. If, on the other hand, the date of birth is parsed as 11
+     * December 15, that will be interpreted as 10 December 1915.
+     *
+     * @function
+     * @param {string} idNumber - The ID number to be parsed.
+     * @return {?Date} The date of birth from the ID number, or undefined if the
+     *   ID number is not formatted correctly or does not have a valid date of
+     *   birth.
+     *
+     * @example
+     * var saIdParser = require('south-african-id-parser');
+     * var validIdNumber = '9001049818080';
+     * var dateOfBirth = saIdParser.parseDateOfBirth(validIdNumber);
+     *
+     * // dateOfBirth === new Date(1990, 01, 04)
+     */
     parseDateOfBirth: parseDateOfBirth,
+
+    /**
+     * Parses the sex out of the ID number and returns true it is male.
+     *
+     * Minimal validation of the ID number is performed, requiring only that
+     * it's 13 digits long.
+     *
+     * @function
+     * @param {string} idNumber - The ID number to be parsed.
+     * @return {?bool} True if male, false if female. Returns undefined if the
+     *   ID number is not a 13 digit number.
+     *
+     * @example
+     * var saIdParser = require('south-african-id-parser');
+     * var validIdNumber = '9001049818080';
+     * var isMale = saIdParser.parseIsMale(validIdNumber);
+     *
+     * // isMale === true
+     */
     parseIsMale: parseIsMale,
+
+    /**
+     * Parses the sex out of the ID number and returns true it is female.
+     *
+     * Minimal validation of the ID number is performed, requiring only that
+     * it's 13 digits long.
+     *
+     * @function
+     * @param {string} idNumber - The ID number to be parsed.
+     * @return {?bool} True if female, false if male. Returns undefined if the
+     *   ID number is not a 13 digit number.
+     * @example
+     * var saIdParser = require('south-african-id-parser');
+     * var validIdNumber = '9001049818080';
+     * var isFemale = saIdParser.parseIsFemale(validIdNumber);
+     *
+     * // isFemale === false
+     */
     parseIsFemale: parseIsFemale,
+
+    /**
+     * Parses the citizenship status out of an ID number and returns true if it
+     * indicates South African citizen.
+     *
+     * Minimal validation of the ID number is performed, requiring only that
+     * it's 13 digits long.
+     *
+     * @function
+     * @param {string} idNumber - The ID number to be parsed.
+     * @return {?bool} True if the ID number belongs to a South African
+     *   citizen. Returns undefined if the ID number is not a 13 digit number.
+     *
+     * @example
+     * var saIdParser = require('south-african-id-parser');
+     * var validIdNumber = '9001049818080';
+     * var isSouthAfricanCitizen = saIdParser.parseIsSouthAfricanCitizen(validIdNumber);
+     *
+     * // isSouthAfricanCitizen === true
+     */
     parseIsSouthAfricanCitizen: parseIsSouthAfricanCitizen
   };