From 1b247dd0c7223dbaa70d0f1cdacab0286d0481ec Mon Sep 17 00:00:00 2001
From: John Reilly <johnny_reilly@hotmail.com>
Date: Fri, 22 Aug 2014 12:09:25 +0100
Subject: [PATCH] AngularJS: Genericised angular.copy and added JSDoc

---
 angularjs/angular-tests.ts | 31 +++++++++++++++++++++++++++++++
 angularjs/angular.d.ts     | 15 ++++++++++++++-
 2 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/angularjs/angular-tests.ts b/angularjs/angular-tests.ts
index 220a63dec1..2e19760e80 100644
--- a/angularjs/angular-tests.ts
+++ b/angularjs/angular-tests.ts
@@ -569,3 +569,34 @@ angular.module('docsTabsExample', [])
             templateUrl: 'my-pane.html'
         };
     });
+
+interface copyExampleUser {
+    name?: string;
+    email?: string;
+    gender?: string;
+}
+
+interface copyExampleScope {
+
+    user: copyExampleUser;
+    master: copyExampleUser;
+    update: (copyExampleUser) => any;
+    reset: () => any;
+}
+
+angular.module('copyExample', [])
+    .controller('ExampleController', ['$scope', function ($scope: copyExampleScope) {
+        $scope.master = { };
+
+        $scope.update = function (user) {
+            // Example with 1 argument
+            $scope.master = angular.copy(user);
+        };
+
+        $scope.reset = function () {
+            // Example with 2 arguments
+            angular.copy($scope.master, $scope.user);
+        };
+
+        $scope.reset();
+    }]);
\ No newline at end of file
diff --git a/angularjs/angular.d.ts b/angularjs/angular.d.ts
index 2f2c68becf..0fc44d9760 100755
--- a/angularjs/angular.d.ts
+++ b/angularjs/angular.d.ts
@@ -42,7 +42,20 @@ declare module ng {
         bootstrap(element: JQuery, modules?: any[]): auto.IInjectorService;
         bootstrap(element: Element, modules?: any[]): auto.IInjectorService;
         bootstrap(element: Document, modules?: any[]): auto.IInjectorService;
-        copy(source: any, destination?: any): any;
+
+        /**
+         * Creates a deep copy of source, which should be an object or an array.
+         * 
+         * - If no destination is supplied, a copy of the object or array is created.
+         * - If a destination is provided, all of its elements (for array) or properties (for objects) are deleted and then all elements/properties from the source are copied to it.
+         * - If source is not an object or array (inc. null and undefined), source is returned.
+         * - If source is identical to 'destination' an exception will be thrown.
+         * 
+         * @param source The source that will be used to make a copy. Can be any type, including primitives, null, and undefined.
+         * @param destination Destination into which the source is copied. If provided, must be of the same type as source.
+         */
+        copy<T>(source: T, destination?: T): T;
+
         element: IAugmentedJQueryStatic;
         equals(value1: any, value2: any): boolean;
         extend(destination: any, ...sources: any[]): any;