[Forms] Add clarifying comments

Add in-line documentation to directives and
controller used for the Forms component. WTD-530.

platform/forms/src/MCTControl.js

@@ -5,6 +5,14 @@ define(
     function () {
         "use strict";
 
+        /**
+         * The mct-control will dynamically include the control
+         * for a form element based on a symbolic key. Individual
+         * controls are defined under the extension category
+         * `controls`; this allows plug-ins to introduce new form
+         * control types while still making use of the form
+         * generator to ensure an overall consistent form style.
+         */
         function MCTControl(controls) {
             var controlMap = {};
 

platform/forms/src/MCTForm.js

@@ -11,6 +11,21 @@ define(
         var MATCH_ALL = /^.*$/;
 
         /**
+         * The mct-form directive allows generation of displayable
+         * forms based on a declarative description of the form's
+         * structure.
+         *
+         * This directive accepts three attributes:
+         *
+         * * `ng-model`: The model for the form; where user input
+         *   where be stored.
+         * * `structure`: The declarative structure of the form.
+         *   Describes what controls should be shown and where
+         *   their values should be read/written in the model.
+         * * `name`: The name under which to expose the form's
+         *   dirty/valid state. This is similar to ng-form's use
+         *   of name, except this will be made available in the
+         *   parent scope.
          *
          * @constructor
          */
@@ -50,6 +65,8 @@ define(
                     return regexps[pattern];
                 }
 
+                // Publish the form state under the requested
+                // name in the parent scope
                 $scope.$watch("mctForm", function (mctForm) {
                     if ($scope.name) {
                         $scope.$parent[$scope.name] = mctForm;
@@ -60,12 +77,26 @@ define(
             }
 
             return {
+                // Only show at the element level
                 restrict: "E",
+
+                // Load the forms template
                 templateUrl: templatePath,
+
+                // Use the controller defined above to
+                // populate/respond to changes in scope
                 controller: controller,
+
+                // Initial an isolate scope
                 scope: {
-                    structure: "=",
+
+                    // The model: Where form input will actually go
                     ngModel: "=",
+
+                    // Form structure; what sections/rows to show
+                    structure: "=",
+
+                    // Name under which to publish the form
                     name: "@"
                 }
             };

platform/forms/src/controllers/DateTimeController.js

@@ -6,8 +6,17 @@ define(
 
         var DATE_FORMAT = "YYYY-DDD";
 
+        /**
+         * Controller for the `datetime` form control.
+         * This is a composite control; it includes multiple
+         * input fields but outputs a single timestamp (in
+         * milliseconds since start of 1970) to the ngModel.
+         *
+         * @constructor
+         */
         function DateTimeController($scope) {
 
+            // Update the
             function update() {
                 var date = $scope.datetime.date,
                     hour = $scope.datetime.hour,
@@ -23,6 +32,7 @@ define(
                 }
             }
 
+            // Update value whenever any field changes.
             $scope.$watch("datetime.date", update);
             $scope.$watch("datetime.hour", update);
             $scope.$watch("datetime.min", update);