[ui/modules] added docs

src/ui/public/modules.js

@@ -1,9 +1,43 @@
+/**
+ * This module is used by Kibana to create and reuse angular modules. Angular modules
+ * can only be created once and need to have their dependencies at creation. This is
+ * hard/impossible to do in require.js since all of the dependencies for a module are
+ * loaded before it is.
+ *
+ * Before taking this approach we saw three possible solutions:
+ *  1. replicate our js modules in angular modules/use a different module per file
+ *  2. create a single module outside of our js modules and share it
+ *  3. use a helper lib to dynamically create modules as needed.
+ *
+ * We decided to go with #3
+ *
+ * This ends up working by creating a list of modules that the code base creates by
+ * calling `modules.get(name)` with different names, and then before bootstrapping
+ * the application kibana uses `modules.link()` to set the dependencies of the "kibana"
+ * module to include every defined module. This guarantees that kibana can always find
+ * any angular dependecy defined in the kibana code base. This **also** means that
+ * Private modules are able to find any dependency, since they are injected using the
+ * "kibana" module's injector.
+ *
+ * RECOMMENDATIONS:
+ *  - just use the "kibana" module for everything
+ *  - rely on js modules for modularity
+ *  - use Private modules for everything except directives and filters
+ *
+ */
 define(function (require) {
   var angular = require('angular');
   var existingModules = {};
   var _ = require('lodash');
   var links = [];
 
+  /**
+   * Take an angular module and extends the dependencies for that module to include all of the modules
+   * created using `ui/modules`
+   *
+   * @param  {AngularModule} module - the module to extend
+   * @return {undefined}
+   */
   function link(module) {
     // as modules are defined they will be set as requirements for this app
     links.push(module);
@@ -12,6 +46,19 @@ define(function (require) {
     module.requires = _.union(module.requires, _.keys(existingModules));
   }
 
+  /**
+   * The primary means of interacting with `ui/modules`. Returns an angular module. If the module already
+   * exists the existing version will be returned. `dependencies` are either set as or merged into the
+   * modules total dependencies.
+   *
+   * This is in contrast to the `angular.module(name, [dependencies])` function which will only
+   * create a module if the `dependencies` list is passed and get an existing module if no dependencies
+   * are passed. This requires knowing the order that your files will load, which we can't guarantee.
+   *
+   * @param  {string} moduleName - the unique name for this module
+   * @param  {array[string]} [requires=[]] - the other modules this module requires
+   * @return {AngularModule}
+   */
   function get(moduleName, requires) {
     var module = existingModules[moduleName];