From a04b30a3839369002734cad54a06d7067d92e2cd Mon Sep 17 00:00:00 2001
From: Victor Woeltjen <victor.woeltjen@nasa.gov>
Date: Fri, 28 Nov 2014 14:36:00 -0800
Subject: [PATCH] [Forms] Add clarifying comments

Add in-line documentation to directives and
controller used for the Forms component. WTD-530.
---
 platform/forms/src/MCTControl.js              |  8 +++++
 platform/forms/src/MCTForm.js                 | 33 ++++++++++++++++++-
 .../src/controllers/DateTimeController.js     | 10 ++++++
 3 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/platform/forms/src/MCTControl.js b/platform/forms/src/MCTControl.js
index b630b72182..2197ac4424 100644
--- a/platform/forms/src/MCTControl.js
+++ b/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 = {};
 
diff --git a/platform/forms/src/MCTForm.js b/platform/forms/src/MCTForm.js
index 6cdcb4deda..986c4d2ddc 100644
--- a/platform/forms/src/MCTForm.js
+++ b/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: "@"
                 }
             };
diff --git a/platform/forms/src/controllers/DateTimeController.js b/platform/forms/src/controllers/DateTimeController.js
index 2b29a13c85..d5a08859f1 100644
--- a/platform/forms/src/controllers/DateTimeController.js
+++ b/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);