Add additional documentation to code/tests

src/Parameter.ts

@@ -28,6 +28,7 @@ export default class Parameter implements ICalElement {
      *
      * @author Mark Stenglein
      * @since 0.1.0
+     * @access public
      * @param inName string The name of the new Parameter in iama-token / x-name
      * @param inValues string[] array of string values
      */
@@ -58,6 +59,7 @@ export default class Parameter implements ICalElement {
      *
      * @author Mark Stenglein <mark@stengle.in>
      * @since 0.1.0
+     * @access public
      * @param newName The new name to be tested and saved.
      * @returns void
      * @throws TypeError if newName is not a valid iCal name.
@@ -83,7 +85,10 @@ export default class Parameter implements ICalElement {
      *
      * @author Mark Stenglein <mark@stengle.in>
      * @since 0.1.0
+     * @access public
      * @param newValues The input values to be tested and saved.
+     * @returns void
+     * @throws TypeError if any of the input values are not valid param-value's
      */
     set paramValues(newValues: string[]) {
         newValues.forEach(newValue => {
@@ -109,6 +114,7 @@ export default class Parameter implements ICalElement {
      *
      * @author Mark Stenglein
      * @since 0.1.0
+     * @access public
      * @returns string Representation of the Parameter as defined in RFC 5545
      */
     public generate(): string {

src/util.ts

@@ -16,41 +16,4 @@ export function isAlpha(input: string): boolean {
     return /^[a-zA-Z]+$/.test(input);
 }
 
-/**
- * Checks to see if the input string is a compliant iama-token
- *
- * Definition of iama-token from the spec:
- *
- *     iana-token = 1*(ALPHA / DIGIT / "-")
- *     ; iCalendar identifier registered with IANA
- *
- * @author Mark Stenglein <mark@stengle.in>
- * @since 0.1.0
- * @param input Input string to be tested
- * @returns boolean value of if it is a valid token
- */
-export function isIanaToken(input: string): boolean {
-    return /^[a-zA-Z0-9-]+$/.test(input);
-}
 
-/**
- * Checks to see if the input string is a compliant x-token
- *
- * Definition of x-name from the spec:
- *
- *     x-name = "X-" [vendorid "-"] 1*(ALPHA / DIGIT / "-")
- *     ; Reserved for experimental use.
- *
- *     vendorid = 3*(ALPHA / DIGIT)
- *     ; Vendor identification
- *
- * @author Mark Stenglein <mark@stengle.in>
- * @since 0.1.0
- * @param input Input string to be tested
- * @returns boolean value of if input is a valid experimental token
- *
- * TODO: Implement this!
- */
-export function isXName(input: string): boolean {
-    return true;
-}

test/Parameter.spec.ts

@@ -10,6 +10,12 @@ describe("Parameter", () => {
         expect(Parameter).to.exist;
     });
 
+    /*
+     * Note: it is not neccessary to test all of the behavior for the
+     * constructor as far as validation of input data is concerned. This is
+     * because the SET method for each property performs that function. Look
+     * there for tests.
+     */
     describe("constructor()", () => {
         it("Should create an object", () => {
             const result: Parameter = new Parameter("TestName", ["value"]);
@@ -25,6 +31,11 @@ describe("Parameter", () => {
         });
     });
 
+    /*
+     * All the GET methods are really doing is pulling the private data
+     *  variables out for the requester to see. Nothing too complex is happening
+     *  that needs to be tested.
+     */
     describe("GET Methods", () => {
         describe("paramName", () => {
             it("Should return the correct name", () => {
@@ -49,6 +60,22 @@ describe("Parameter", () => {
         });
     });
 
+    /*
+     * Note that the SET methods are difficult to directly test, as they are
+     *  called even by the constructor function when setting the values. Because
+     *  of that behavior, they can be tested directly by simply calling the
+     *  class constructors with the values you want to test.
+     *
+     * The constructor is really only going so far as to do this:
+     *
+     *     constructor(inName: string, inValues: string[]) {
+     *         this.paramName = inName;
+     *         this.paramValues = inValues;
+     *     }
+     *
+     * These tests implement the data validation that is missing from the
+     *  constructor level tests.
+     */
     describe("SET Methods", () => {
         describe("paramName", () => {
             it("Correctly sets iana-token names", () => {
@@ -79,6 +106,19 @@ describe("Parameter", () => {
         });
     });
 
+    /**
+     * Tests the generation of param strings to make sure they are to spec with
+     *   RFC 5545's ABNF definition (pg. 10):
+     *
+     *     param = param-name "=" param-value *("," param-value)
+     *     ; Each property defines the specific ABNF for the parameters
+     *     ; allowed on the property. Refer to specific properties for
+     *     ; precise parameter ABNF.
+     *
+     * tl;dr of the above snippet is that this is a basic structure check so
+     *   that the higher level classes can simply validate proper types and use
+     *   the lower level generate method.
+     */
     describe("generate()", () => {
         it("Correctly generates single-valued parameters", () => {
 
@@ -93,6 +133,12 @@ describe("Parameter", () => {
         });
     });
 
+    /**
+     * There are currently many more static methods then will be in the final
+     *   class. I need to start building the other objects before I will have a
+     *   better idea which of these validators are unique or need to be moved to
+     *   a general utility file.
+     */
     describe("STATIC Methods", () => {
         /**
          * iana-token definition from RFC 5545 (pg. 10)