From 3d70e55d725288e9a1fcec22d95ba3a075f57e7c Mon Sep 17 00:00:00 2001
From: ghodss
Date: Sun, 11 Aug 2013 16:03:17 -0700
Subject: docs(guide): warn about module creation versus retrieval

Updated Module documentation to include the suggestion of the top-rated comment: "This documentation should warn that "angular.module('myModule', [])" always creates a new module, but "angular.module('myModule')" always retrieves an existing reference."
---
 docs/content/guide/module.ngdoc | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/docs/content/guide/module.ngdoc b/docs/content/guide/module.ngdoc
index a1c02546..8bf0eba6 100644
--- a/docs/content/guide/module.ngdoc
+++ b/docs/content/guide/module.ngdoc
@@ -191,6 +191,24 @@ scripts into a VM. There are existing projects which deal with script loading, w
 with Angular. Because modules do nothing at load time they can be loaded into the VM in any order
 and thus script loaders can take advantage of this property and parallelize the loading process.
 
+## Creation versus Retrieval
+
+Beware that using `angular.module('myModule', [])` will create the module `myModule` and overwrite any
+existing module named `myModule`. Use `angular.module('myModule')` to retrieve an existing module.
+
+<pre>
+  var myModule = angular.module('myModule', []);
+  
+  // add some directives and services
+  myModule.service('myService', ...);
+  myModule.directive('myDirective', ...);
+
+  // overwrites both myService and myDirective by creating a new module
+  var myModule = angular.module('myModule', []);
+
+  // throws an error because myOtherModule has yet to be defined
+  var myModule = angular.module('myOtherModule');
+</pre>
 
 # Unit Testing
 
-- 
cgit v1.2.3