feat(form.FormController): add $getControls()

src/ng/directive/form.js

@@ -4,7 +4,7 @@
  */
 var nullFormCtrl = {
   $addControl: noop,
-  $getControls: noop,
+  $getControls: valueFn([]),
   $$renameControl: nullFormRenameControl,
   $removeControl: noop,
   $setValidity: noop,
@@ -166,16 +166,18 @@ FormController.prototype = {
    * @returns {Array} the controls that are currently part of this form
    *
    * @description
-   * This method returns a **shallow copy** of the controls that are currently part of this form
-   * ({@link form.FormController `FormController`} /
-   * {@link ngModel.NgModelController `NgModelController`}) . This can be used
-   * for example to iterate over all controls to validate them.
+   * This method returns a **shallow copy** of the controls that are currently part of this form.
+   * The controls can be instances of {@link form.FormController `FormController`}
+   * ({@link ngForm "child-forms"}) and of {@link ngModel.NgModelController `NgModelController`}.
+   * If you need access to the controls of child-forms, you have to call `$getControls()`
+   * recursively on them.
+   * This can be used for example to iterate over all controls to validate them.
    *
-   * The controls can be accessed normally, but adding or removing controls from the array has no
-   * effect on the form. Instead, use {@link form.FormController#$addControl `$addControl()`} and
-   * {@link form.FormController#$removeControl `$removeControl()`}.
-   * Likewise, adding a control to / removing a control from the form is not reflected
-   * in the shallow copy. That means you should get a fresh copy from `$getControls` every time
+   * The controls can be accessed normally, but adding to, or removing controls from the array has
+   * no effect on the form. Instead, use {@link form.FormController#$addControl `$addControl()`} and
+   * {@link form.FormController#$removeControl `$removeControl()`} for this use-case.
+   * Likewise, adding a control to, or removing a control from the form is not reflected
+   * in the shallow copy. That means you should get a fresh copy from `$getControls()` every time
    * you need access to the controls.
    */
   $getControls: function() {

test/ng/directive/formSpec.js

@@ -1200,7 +1200,18 @@ describe('form', function() {
     });
   });
 
-  fdescribe('$getControls', function() {
+  describe('$getControls', function() {
+    it('should return an empty array if the controller has no controls', function() {
+      doc = $compile('<form name="testForm"></form>')(scope);
+
+      scope.$digest();
+
+      var form = doc,
+          formCtrl = scope.testForm;
+
+      expect(formCtrl.$getControls()).toEqual([]);
+    });
+
     it('should return a shallow copy of the form controls', function() {
       doc = $compile(
           '<form name="testForm">' +