angular.javascript.txt

                                  ┏━━━━━━━━━━━━━┓
                                  ┃   ANGULAR   ┃
                                  ┗━━━━━━━━━━━━━┛

                                  ┌──────────┐
                                  │   MAIN   │
                                  └──────────┘

JAVASCRIPT FILE ==>                             #angular.js for core modules. There are CDN.
                                                #Should use <script defer> for better responsiveness.
                                                #Other modules are shipped in different JavaScript files, e.g. angular-route.js
                                                #Version: 1.4.0-beta6
                                                #Not compatible with IE<9.0

ANGULAR UI UTILS ==>                           |#angular-ui-utils (version 0.2.2)
                                               |#Noted like this. 
                                               |#MODULE "ui.*". Can use MODULE "ui-utils" to include all sub-MODULE
 
GOAL ==>                                        #Model-View-Controller separation.
                                                #Goal:
                                                #  - put DOM manipulation ("view") in HTML, not JavaScript, using directives.
                                                #  - put dynamic data ("model") in JavaScript, not HTML, using partial 
                                                #    templates and expressions.

STRUCTURE ==>                                   #View-related logic (DOM Manipulation):
                                                #  - DIRECTIVE: 
                                                #    - custom HTML tag, attribute or class
                                                #    - is compiled by COMPILER at bootstrap ("template" -> "views")
                                                #    - communicates with SCOPE by creating:
                                                #       - DOM -> SCOPE: DOM event listener, manipulating SCOPE
                                                #       - SCOPE -> DOM: SCOPE changes listener, manipulating DOM:
                                                #           - use SCOPE.$watch(), which should not evaluate DOM objects, 
                                                #             only SCOPE and as simple as possible (for performance reasons)
                                                #           - some types:
                                                #              - partial templates: chunks of HTML templates, loaded 
                                                #                dynamically according to "route" (pseudo-URL)
                                                #              - {{EXPR}}: dynamic SCOPE VAR put in HTML
                                                #                 - {{EXPR | FILTER}}: FILTER applies modifications to EXPR
                                                #                   Should use FILTER to parse HTML fragment output, not 
                                                #                   CONTROLLER.
                                                #              - dynamic CSS classes: automatically updated according to 
                                                #                DOM/SCOPE change.
                                                #  - ANIMATION:
                                                #     - either CSS, or JavaScript separate unit
                                                #Non-view-related logic (JavaScript):
                                                #  - Reusable (like a library): SERVICE, used by CONTROLLER:
                                                #     - Singleton VAL (usually OBJ or FUNC)
                                                #     - By convention called $VAR for Angular ones (not custom ones)
                                                #     - All components can use them by specifying them in their AFUNC
                                                #     - use dependency injection for easier mocks (see below)
                                                #  - Specific: SCOPE, an OBJ holding data for a HTML node and its children:
                                                #     - initialized/constructed by a CONTROLLER
                                                #       CONTROLLER can also be associated with specific forms/controls, in 
                                                #       which case they implement the logic, but don't have a specific SCOPE.
                                                #     - root SCOPE is defined at bootstrap, and child SCOPE can be created,
                                                #       inheriting or not the data, but always inheriting events.

BEST PRACTICE ==>                               #It is very important to put some code away from CONTROLLER:
                                                #  - code used by several CONTROLLER -> SERVICE
                                                #  - DOM manipulation -> DIRECTIVE
                                                #  - DOM animation -> ANIMATION
                                                #  - HTML output parsing -> FILTER

ORGANIZATION ==>                                #MODULE:
                                                #  - components (SERVICE, SERVICEPROVIDER, CONTROLLER, DIRECTIVE, FILTER) are 
                                                #    bundled into modules, generally a file or a library.
                                                #  - should put for each feature, a FEATURE_DIR/ while files:
                                                #        - FEATURE.js: module declaration
                                                #        - FEATURE-controller|directive|service|filter|animation[_test].js
                                                #Dependency injection:
                                                #  - components declaration is through factory methods registration AFUNC, not
                                                #    instantiation, which are called runtime by the INJECTOR
                                                #  - a MODULE must depend on MODULE2 in order to use/refer to its components
                                                #    Dependencies MODULE_STR_ARR must always start with root dependencies
                                                #  - instead of declare dependencies as constructed arguments to constructors,
                                                #    register them as STR IDs to factory functions, which permits:
                                                #      - easy use of mock dependencies
                                                #      - control of dependencies' dependencies by injector
                                                #      - control of instantiation (singleton, lazy loading, etc.) by injector

OTHER UTILITIES ==>                             #  - client-side routing
                                                #  - client-side forms validation
                                                #  - dynamic lists (ng-repeat, ng-options)
                                                #  - AJAX|REST calls
                                                #  - testing (clock, AJAX mocks)
                                                #  - conditions HTML attributes (ng-show|if|switch|messages)
                                                #  - mobile swipe event
                                                #  - localization

                                  ┌──────────────────────────┐
                                  │   INJECTOR AND MODULES   │
                                  └──────────────────────────┘

angular.bootstrap(ELEM[, MODULE_STR_ARR])       #Does the initialization, i.e.:
                                                #  //Load MODULE and create INJECTOR
                                                #  var INJECTOR = angular.injector(MODULE_STR_ARR); 
                                                #  //Sets $rootElement to ELEM and ELEM.injector() to INJECTOR
                                                #  ...
                                                #  //Compile
                                                #  INJECTOR.invoke(function($rootScope, $compile) { 
                                                #    $compile(ELEM)($rootScope);                   
                                                #    $rootScope.$digest();                   
                                                #  });
                                                #  return INJECTOR;
                                                #Timing:
                                                #  - it throws an error when called twice.
                                                #  - Should be called after DOMContentLoaded is fired, e.g. in:
                                                #     angular.element( document ).ready( FUNC() )
                                                #  - if window.name starts with 'NG_DEFER_BOOTSTRAP!', it waits for 
                                                #    angular.resumeBootstrap(MODULE_STR_ARR) to complete (MODULE are added).
                                                #    Used by plugins (e.g. Chrome extensions) to add modules on Angular pages
<any>                                           #Does angular.bootstrap(<any>, [MODULE])
  ng-app[=MODULE]                               #Usually <html> but not necessarily.

angular.injector(MODULE_STR_ARR)                #Returns an INJECTOR loading all components of MODULE_STR_ARR.
AJQ.injector()                                  #Returns element root scope's INJECTOR.
                                                #Usually done on $rootElement
$injector                                       #Same as a SERVICE
INJECTOR.get(SERVICE_STR)                       #Returns SERVICE.
INJECTOR.invoke(AFUNC(SERVICE...)[, this][,OBJ])#Similar but here fires AFUNC and provides SERVICE... as arguments.
                                                #OBJ can overwrite SERVICE..., e.g. { $SERVICE: MOCK_OBJ }
INJECTOR.instantiate(...)                       #Same but fires and returns new AFUNC.
INJECTOR.has(SERVICE_STR)                       #Returns true if exists.

AFUNC ==>                                       #FUNC(SERVICE...). 
                                                #INJECTOR will automatically provide SERVICE... (through INJECTOR.get())
                                                #SERVICE argument name should be SERVICE name.
                                                #To specify them while still being able to minimize the code, must use either:
                                                #  - after FUNC declaration: 
                                                #      FUNC["$inject"] = STR_ARR
                                                #  - or during FUNC declaration, instead of AFUNC(...):
                                                #      [ STR..., AFUNC(...) ]
                                                #Where STR[_ARR] are the FUNC arguments names as STR.
                                                #Can use <any ng-app ng-strict-di> to force using [ STR..., AFUNC(...) ] 
                                                #instead of AFUNC(...), or angular.bootstrap(..., { strictDi: true })
                                                #Can put just FUNC() if no SERVICE.
ng-annotate FILE                               ##Prints to stdout FILE (JavaScript) (can be - for stdin):
                                               ##  - if --remove, [ STR..., AFUNC(...) ] -> AFUNC(...)
                                               ##  - if --add, inverse
                                               ##  - can do --add --remove to rebuild everything
                                               ##Goal is not to have annotations in source, and have it in production.
                                               ##If problem with specific line of code, use /* @ngInject */ or ngInject(AFUNC)
                                               ##Version 0.10.1
--single_quotes                                ##Uses '$SERVICE' instead of "$SERVICE"
--regexp REGEXP_STR                            ##Excludes matching SERVICE name (full match)
--sourcemap
--sourceroot DIR                               ##Inline source map
GULP-NG-ANNOTATE([OBJ])                        ##OBJ: single_quotes BOOL, remove BOOL, add BOOL, regexp, sourcemap, sourceroot
                                               ##Version 0.3.6

ng                                              #Main MODULE, including all core services and components.

angular.module( MODULE_STR, MODULE2_STR_ARR     #Registers factory method for a MODULE depending on MODULE2_STR_ARR, and 
[, AFUNC([SERVICE...])])                        #returns it. "ng" is implicitely added.
                                                #Using AFUNC(...) is like calling MODULE.config(...)
angular.module( MODULE_STR )                    #Returns a MODULE.
MODULE.name                                     #MODULE_STR
MODULE.requires                                 #MODULE2_STR_ARR passed at construction.

MODULE.run(AFUNC([SERVICE...]))                 #Will run AFUNC every time MODULE is finished being loaded by an INJECTOR.

$rootElement                                    #SERVICE AJQ, representing the root element of angular.bootstrap()

COMPILE-TIME CHANGES ==>                        #Modifying SERVICE:
                                                #  - Service providers (called $SERVICEProvider): API provided by SERVICE
                                                #  - Decorators: adding your own changes to SERVICE

RUNTIME CHANGES ==>                             #Possible runtime changes:
                                                #  - adding directives or EXPR 
                                                #    -> compile again the element, with:
                                                #         AJQ.injector().invoke(function($compile) { 
                                                #           $compile(ELEM|HTML_STR)(AJQ.scope());
                                                #           AJQ.scope().$digest();
                                                #         })
                                                #  - modifying SERVICE
                                                #    -> INJECTOR.get|invoke()
                                                #        - overridden if new angular.injector() call
                                                #        - not with MODULE.value|constant()
                                                #    -> MODULE.config or PROVIDE.decorator()
                                                #        - must call angular.injector() again to load them
                                                #  - adding MODULE components (except PROVIDE.decorator())
                                                #    -> call angular.injector() again to load them

                                  ┌─────────────┐
                                  │   SERVICE   │
                                  └─────────────┘

RIGHT TYPE OF SERVICE ==>                       #If SERVICE:
                                                #  - must encapsulate members:
                                                #     - that can be configured by client -> MODULE.provider()
                                                #     - otherwise: 
                                                #        - SERVICE inherits from another object -> MODULE.service()
                                                #        - otherwise -> MODULE.factory()
                                                #  - otherwise:
                                                #     - can be configured by client -> MODULE.constant()
                                                #     - otherwise -> MODULE.value()
                                                #All components are actually SERVICE

MODULE.provider(SERVIC_STR,AFUNC                #Registers factory method for SERVICE and SERVICEPROVIDER.
([SERVICEPROVIDER2...]))                        #AFUNC must return an OBJ:
                                                #  - it must have a member $get FUNC() returning VAL: this is the SERVICE
                                                #  - OBJ is the SERVICEPROVIDER:
                                                #     - can be manipulated in MODULE.config() as SERVICE_STRProvider
                                                #     - members other than $get are encapsulated for SERVICE, but available
                                                #       in SERVICEPROVIDER. They must change the way SERVICE will operate
                                                #       (so $get() should reference to them)
MODULE.factory(SERVICE_STR,AFUNC([SERVICE2...]))#Same but:
                                                #  - AFUNC must return a VAL: the SERVICE.
                                                #  - can use SERVICE2, not only SERVICEPROVIDER2
                                                #Easier but no SERVICEPROVIDER is defined.
                                                #Variables defined in AFUNC but not returned are encapsulated, but cannot be
                                                #configured.
MODULE.service(SERVICE_STR,AFUNC([SERVICE2...]))#Same but AFUNC must set this: the SERVICE (AFUNC will be called with new).
MODULE.value|constant(SERVICE_STR, VAL)         #Same but with a VAL. 
                                                #Difference between both is the way they can be modified:
                                                #  - constant can be used in config() as a SERVICEPROVIDER
                                                #  - value can be used in PROVIDE.decorator(), or using MODULE.value() again.
GULP-NG-CONSTANT(OBJ)                           #Creates a file containing a definition:
                                                #  angular.module(SERVICE_STR, MODULE_ARR)
                                                #    .constant(SERVICE2_STR, VAL)
                                                #    ...
                                                #Where:
                                                #  - source IOSTREAM is a JSON of SERVICE2_STR/VAL
                                                #  - dest IOSTREAM is the file containing definition
                                                #OBJ:
                                                #  - name SERVICE_STR
                                                #  - deps MODULE_ARR
                                                #  - constants OBJ: to merge to JSON
                                                #  - wrap "amd|commonjs" (def: null) ("commonjs" adds "module.exports =")
                                                #  - space STR (def: "\t"): for JSON.stringify()
                                                #  - template[Path]: for further customization (should not be needed)
                                                #Can also put OBJ directly in JSON file
                                                #Version 0.1.1

MODULE.config(AFUNC(SERVICEPROVIDER...))        #Returns a SERVICEPROVIDER with AFUNC(), in order to configure the
                                                #underlying SERVICE.

$provide                                        #SERVICEPROVIDER, used to create services and components:
                                                #  - MODULE.provider(...) is an alias of:
                                                #      MODULE.config(AFUNC($provide){ $provide.provider(...) })
                                                #  - Other functions, or SERVICEPROVIDER 
                                                #    $animateProvider,$filterProvider,$controllerProvider,$compileProvider,etc.
                                                #    exist but are not referenced here because useless.
PROVIDE.decorator(SERVICE_STR,                  #Substitute original SERVICE:
AFUNC([SERVICE2...]))                           #  - return a VAL which is the new SERVICE
                                                #  - original SERVICE is available in service $delegate.
                                                #    Usually add|substitute some members, then return it
                                                #Used to change a SERVICE outside what's allowed in its SERVICEPROVIDER, or 
                                                #implement mocks.

                                  ┌───────────┐
                                  │   SCOPE   │
                                  └───────────┘

$exceptionHandler                               #SERVICE FUNC, fired when an exception is thrown by Angular.
EXPRESSIONHANDLER(ERROR, STR)                   #STR is ERROR.name for example.
                                                #Default behavior does $log.error(ERROR, STR)

$rootScope                                      #SERVICE, pointing at the root SCOPE.

$scope                                          #SERVICE, used only in CONTROLLER
SCOPE.id                                        #STR
AJQ.scope()                                     #Returns element's non-isolated SCOPE (first non-isolated one if current is 
                                                #isolated).
AJQ.isolateScope()                              #Returns element's isolated SCOPE (if current is non-isolated, returns null).
SCOPE.$new(BOOL[, SCOPE3])                      #Creates and returns a child SCOPE2:
                                                #  - parent is SCOPE3 (def: SCOPE)
                                                #  - $digest() called on parent, call it too on children.
                                                #  - $broadcasted events are sent to children.
                                                #  - if BOOL false (déf), is non-isolated, i.e.:
                                                #     - inherits by reference variables declared in parent 
                                                #     - but child changes create a child-specific copy
SCOPE.$parent                                   #
SCOPE.$root                                     #

SCOPE.$eval(EXPR|FUNC(SCOPE)[, OBJ])            #Evaluates EXPR in SCOPE context, i.e. does $parse(EXPR)(SCOPE[, OBJ]), and 
                                                #returns result.
                                                #Can also use FUNC(SCOPE), which execute any code, and can return result.
                                                #EXPR doesn't have access to DOM or to angular.* but FUNC(SCOPE) does, and is 
                                                #XSS-safer.
SCOPE.$evalAsync(EXPR_STR|FUNC(SCOPE)[, OBJ])   #Same but executes async., which implies:
                                                #  - executes at least after current FUNC returns
                                                #  - $digest() will be called after it executes
                                                #  - doesn't return anything.
SCOPE.$watch(EXPR_STR|FUNC(SCOPE),              #At each $digest(), if current $eval(ARG1) != previous $eval(ARG1), fires
STR2|FUNC(VAL,VAL2,SCOPE)[, BOOL])              #$evalAsync(ARG2) (VAL is new value, VAL2 old one).  
                                                #!= is:
                                                #  - if false !== (déf) 
                                                #  - if true: ! angular.equals(VAL, VAL2): like VAL === VAL2, but:
                                                #     - also compare OBJ recursively (except DOM elements), except members 
                                                #       FUNC or with key starting with "$"
                                                #     - NaN and REGEXP returns true when same (as opposed to JavaScript)
                                                #If $evalAsync() changes ARG1 again, call recursively (up to 10 times).
                                                #Listener is fired async. right away when $watch() is called too.
                                                #Can check VAL === VAL2, to be sure listener is called because of change and
                                                #not initialization.
                                                #Watched expression should be as simple as possible for performance reason.
                                                #Returns FUNC(), which turns it off.
SCOPE.$watchCollection(...)                     #Same but ARG1 and ARG2 use OBJ, and $watches all members.
                                                #Not exactly same arguments: ARG2 must be FUNC, and BOOL is always false.
SCOPE.$watchGroup(...)                          #Same for ARR
SCOPE.$digest()                                 #Triggers $watch listening
                                                #Prefer using $apply()
SCOPE.$apply([EXPR_STR|FUNC(SCOPE)])            #Every JavaScript EXPR evaluated in SCOPE must use SCOPE.$apply(EXPR) in order 
                                                #to:
                                                #  - call $eval(EXPR) and return result.
                                                #  - catch exceptions with $exceptionHandler()
                                                #  - call $digest() in the end
                                                #Angular expressions, e.g. JavaScript in CONTROLLER AFUNC or call to 
                                                #SERVICE.FUNC() don't need it (usually $apply() is used underneath)
SCOPE.$applyAsync(...)                          #Same as SCOPE.$apply(), but only called at the next $apply() or after short
                                                #timeout (around 10ms). 
                                                #Allows queuing $apply() together for better performance.

SCOPE.$on(AEVENT_STR, FUNC(AEVENT[, ...]))      #As opposed to DOM events, are limited to SCOPE, and can provide arguments.
                                                #AEVENT has members: 
                                                #  - name STR
                                                #  - targetScope and currentScope SCOPE: similar to DOM target and 
                                                #    currentTarget
                                                #  - stopPropagation FUNC, preventDefault FUNC and defaultPrevented BOOL: 
                                                #    like DOM, but for Angular events, and stopPropagation() can only be 
                                                #    called for $emitted events.
                                                #Returns a FUNC2(), which turn off the event listener.
SCOPE.$emit|$broadcast(AEVENT_STR[, ...])       #Fires event and propagate to siblings then parents, or siblings then children.
                                                #Returns AEVENT (see above).
SCOPE.$destroy()                                #Will emit a $destroy AEVENT.
                                                #There should be an event listener if some cleanup has to be done 


MODULE.controller(CONTROLLER_STR,               #Registers factory method for a CONTROLLER.
AFUNC([SERVICE...])                             #AFUNC doesn't return anything but must initialize a SCOPE.
                                                #Can use special CONTROLLER services: 
                                                #  - $scope SCOPE
                                                #  - $element AJQ: current element
                                                #  - $attrs ATTRS (see below)
                                                #CONTROLLER will be called when compiling <any ng-controller=CONTROLLER_STR>
                                                #HTML tag will have class="ng-[isolate-]scope" then.
<any>                                           #If SCOPE_VAR:
  ng-controller="CONTROLLER[ as SCOPE_VAR]"     #  - CONTROLLER_AFUNC access SCOPE with this, not $scope
                                                #  - EXPR uses SCOPE_VAR.VAR2, not VAR2, which is more verbose, doesn't allow
                                                #    inheritance, but allow manually selecting the SCOPE
AJQ.controller([DIRECTIVE_STR])                 #Returns a CONTROLLER, only for:
                                                #  - FORM|NGMODELCONTROLLER
                                                #  - directive if DIRECTIVE_STR

<any>                                           #Evaluates EXPR at compile time (usually "VAR = VAL")
  ng-init="EXPR"                                #Should be avoided (use CONTROLLER instead)

                                  ┌────────────────┐
                                  │   DIRECTIVES   │
                                  └────────────────┘

COMPILATION ==>                                 #Compiler looks for following in HTML:
                                                #  <my-dir></my-dir> (prefer for new entity/functionality)
                                                #  <any my-dir="VAL"> (prefer for adding functionality)
                                                #  <any class="my-dir=VAL"> (deprecated)
                                                #And fires myDir DIRECTIVE.
                                                #Transform HTML (AJQ to AJQ2). Detailed steps:
                                                #  - compile FUNC(AJQ, ATTRS): 
                                                #      - fired by $compile(ELEM|HTML_STR)
                                                #      - non-SCOPE specific tasks: change DOM content
                                                #      - returns link FUNC(...), so cannot specify together with link FUNC
                                                #  - link FUNC(SCOPE, AJQ, ATTRS):
                                                #      - returns new AJQ2
                                                #      - SCOPE specific tasks: setup DOM event listeners and/or SCOPE $watch()
                                                #      - SCOPE.$digest() is not called automatically if done manually, but
                                                #        is done when bootstrapping.
                                                #      - can divide between a pre and post link phases:
                                                #         - must use { pre|post FUNC(...) } instead of link FUNC or compile
                                                #           return value
                                                #         - if not specified, assumes post link
                                                #         - pre link is when no DOM manipulation, post link when there is.
                                                #Controllers are called between compile and link.

MODULE.directive(DIRECTIVE_STR,                 #Tells the compiler to modify current HTML tag children and/or execute some 
AFUNC([SERVICE...]))                            #JavaScript if its tag, element or class names are matching DIRECTIVE_STR.
                                                #TAG refer to the element.
                                                #AFUNC can return FUNC (same as { link: FUNC }) or OBJ with members:
                                                #  - compile FUNC(TAG_AJQ, ATTRS)->FUNC(...): see above
                                                #  - link FUNC(SCOPE, TAG_AJQ, ATTRS)->AJQ2: see above
                                                #  - template HTML_STR|FUNC(TAG_AJQ, ATTRS)->HTML_STR: simpler syntax for 
                                                #    compile FUNC which replaces TAG children by HTML_STR.
                                                #    If specified with compile|link, run as a sort of pre-compile function.
                                                #    Uses SCE.RESOURCE_URL
                                                #  - templateUrl URL|FUNC(TAG_AJQ, ATTRS)->URL
                                                #  - templateNamespace "html|svg|math" (def: "html"): type of template
                                                #  - restrict "[A][E][C]" (def: "EA"): what to match among "A" (attribute), 
                                                #    "E" (tag), "C" (class).
                                                #  - multiElement BOOL: if true:
                                                #     - TAG will include several elements (possibly empty text nodes), i.e.
                                                #       anything between DIRECTIVE-start[="..."] and DIRECTIVE-end
                                                #     - can also only use DIRECTIVE for single element
                                                #     - link|compile functions will be called once for all elements, but 
                                                #       template[Url] which are called once for each. 
                                                #  - scope true: creates a non-isolated SCOPE for TAG.
                                                #  - scope { VAR: "sym[ATTR]" ... }: creates an isolated SCOPE for TAG.
                                                #    ATTR (def: "VAR") refers to the element HTML attribute ATTR, which can be,
                                                #    according to "sym":
                                                #     - "@": "VAL"
                                                #     - "=[*][?]": "EXPR"
                                                #        - "?": exceptions are not propagated (e.g. missing VAR)
                                                #        - "*": use $watchCollection(), not $watch()
                                                #     - "&": "EXPR", where VAR([OBJ]) will fire EXPR. If OBJ, merges to scope.
                                                #  - controller AFUNC
                                                #  - controllerAs CONTROLLER_STR: register controller AFUNC, providing SCOPE 
                                                #    OBJ is used
                                                #  - bindToController BOOL|OBJ (def: false): if true and controllerAs STR used,
                                                #    make scope OBJ relative to CONTROLLER's this, not SCOPE
                                                #    Using OBJ is shortcut for bindToController true, scope OBJ
                                                #  - require DIRECTIVE_STR[_ARR]:
                                                #     - current element must have DIRECTIVE[_ARR] or throws exception (unless
                                                #       STR starts with "?"
                                                #     - look into parent elements too|only if STR begins with ^|^^
                                                #     - DIRECTIVE[_ARR] must have a controller FUNC:
                                                #        - FUNC's this is passed as last arg OBJ[_ARR] to link FUNC
                                                #        - OBJ is null if using "?DIRECTIVE" and DIRECTIVE doesn't exist.
                                                #        - This is the preferred way to communicate to children DIRECTIVE 
                                                #          without polluting current SCOPE, and bypassing isolated scopes.
                                                #  - transclude true|"element": 
                                                #      - after compile FUNC, replace ... of <TAG ng-transclude>...</TAG> 
                                                #        by original TAG and its children. 
                                                #      - if "element", targets also <TAG ng-tranclude> itself
                                                #      - ... gets a new non-isolated child SCOPE2
                                                #        If directive creates an isolated scope, it will not cover ...
                                                #      - can also use $tranclude([SCOPE2, ]FUNC(AJQ, SCOPE2)[, AJQ2])->AJQ 
                                                #        SERVICE in a CONTROLLER or fifth argument $tranclude(...) in link 
                                                #        function
                                                #         - usually not needed for most cases
                                                #         - FUNC() should attach AJQ (is a copy) to new place
                                                #         - SCOPE2 can be overriden with first arg. By def, it is a new
                                                #           non-isolated scope.
                                                #         - AJQ2 is AJQ parent (def: current parent)
                                                #  - type "html|svg|math": type of the children (déf: "html")
                                                #There can be:
                                                #  - several calls to same DIRECTIVE_STR: appends, do not overwrite.
                                                #    Use same priority as below.
                                                #  - AJQ with several DIRECTIVE, which behaves according to OBJ:
                                                #     - priority INT (déf: 0): lower are first called. If same, last declared 
                                                #       first called.
                                                #     - terminal BOOL: if true, do not do any DIRECTIVE with lower priority
                                                #       (make sure it is called last).
<any>
  ng-non-bindable                               #Does not compile. Used e.g. to show Angular.js snippets inside an Angular app.

uiAliasConfig                                  |#Redefining ANGULAR.constant(DIRECTIVE_STR, HTML_STR) creates a DIRECTIVE with
                                               |#{ template: HTML_STR, replace: true }
                                               |#MODULE "ui.alias"

ATTRS                                           #OBJ representing the HTML attributes of a tag.
                                                #Used in directives and controllers.
                                                #Should use them to manipulate attributes, since they fire ANIMEVENT
ATTRS.ATTR                                      #For each HTML attribute.
ATTRS.$set(STR, VAL)                            #Changes an attributes VAL
ATTRS.$add|removeClass(CLASS_STR) 
ATTRS.$updateClass(CLASS_STR, CLASS2_STR)       #Add/remove CSS classes by calling ANIMATE.add|removeClass()
ATTRS.$observe(ATTR_STR, FUNC2(ATTR_VAL))       #Like $watch listener on attribute change but is notified not by $digest() but
                                                #by ATTRS.$set()
                                                #Automatically done in an attr="{{EXPR}}"
ATTRS.$normalize(STR)                           #Gets camelcase from dash-based attribute

$compileProvider.debugInfoEnabled(BOOL)         #If true (def), adds CSS class .ng-binding to elements with {{EXPR}} and class
                                                #.ng-scope to elements with scopes.
                                                #They are used by tools like Batarang or Protactor. 
                                                #Setting to false provides performance boost.
angular.reloadWithDebugInfo()                   #Reload page but calls $compileProvider.debugInfoEnabled(true) at beginning

                                                

                                  ┌─────────────────────────────┐
                                  │   EXPRESSIONS AND FILTERS   │
                                  └─────────────────────────────┘

EXPR                                            #STR like JavaScript, which use native objects, but: 
                                                #  - only those native operators/keywords: NaN, Infinity, + - * / % ! && ||
                                                #  - Doesn't throw exception when accessing properties of null|undefined, e.g.
                                                #    "VAR.VAR2" when VAR is null.
                                                #  - cannot access the DOM
                                                #  - Can use FILTER

$parse                                          #SERVICE FUNC, used to evaluate EXPR
PARSE(EXPR)                                     #Returns FUNC2, with must be fired as FUNC2([{VAR: VAL ...}[, OBJ2]]), which 
                                                #evaluates EXPR with environment { VAR: VAL ... } and returns result.
                                                #OBJ2 is used to overwrite OBJ.
                                                #Can also:
                                                #  - use FUNC2.parse|literal BOOL: whether top-level|all expressions in 
                                                #    STR are pure JavaScript (not referencing SCOPE or the DOM).
                                                #  - use FUNC2.assign(OBJ, VAL), which assign VAL to a member of OBJ according
                                                #    to EXPR, e.g. PARSE("a.b").assign({a:{b: 3}}, 4) will turn 3 to 4
                                                #    (in OBJ, not in EXPR)

$interpolate                                    #SERVICE FUNC, used to evaluate {{EXPR}}
INTERPOLATE(STR[, BOOL[, CONTEXT[, BOOL2]]])    #Same as $parse, but with start and end symbols.
                                                #If BOOL true and doesn't contain {{...}}, returns undefined.
                                                #If CONTEXT, will then wrap with SCE.getTrusted(CONTEXT, ...), and STR can't
                                                #have interlaced {{EXPR}}
                                                #If BOOL2 true and one embedded expression returns undefined, the whole returns
                                                #undefined.
INTERPOLATE.start|endSymbol()                   #"{{" or "}}". Can be changed by $interpolateProvider.start|endSymbol([STR])

{{EXPR}}                                        #Sets up a $watch for EXPR, and replaces it with $interpolate(EXPR)(SCOPE) 
                                                #every time it changes.
                                                #Can be used in text nodes or in most attribute values.
                                                #Parent node will get class ng-binding.
                                                #Can be interlaced {{EXPR}} in normal STR, i.e. "...{{...}}...{{...}}", where
                                                #the parts not in {{}} will be treated as STR.
{{::EXPR}}                                      #Same but does not update anymore after the first evaluation (static) that
                                                #does not evaluate to undefined.
                                                #To use only for performance reasons.
<any>                                           #Same as <any>{{EXPR}}</any>
  ng-bind="EXPR"                                #{{EXPR}} actually compile to <span ng-bind="EXPR"></span>
  ng-bind-template="STR"                        #Same but a STR containing {{EXPR}}, e.g. "...{{...}}...{{...}}"
                                                #Useful in <option> and <title> (cannot have {{EXPR}})

<any>                                           #Put "display: none" from end of angular.js loading to end of compilation.
  ng-cloak                                      #Goal is to avoid seeing uncompiled {{EXPR}} while loading the app.
                                                #Should not be put once at the root, but many times at the lowest levels 
                                                #possible.

EXPR[ | FILTER[:ARG[:...]]]                     #FILTER post-process EXPR:
                                                #  - can chain them
                                                #  - can take arguments (STR must be enclosed with "")
                                                #  - can also be used as a FUNC in an AFUNC:
                                                #      - as a SERVICE with name FILTERFilter, (not $FILTERFilter) 
                                                #      - with $filter(FILTER_STR)
                                                #  - should be stateless
MODULE.filter(FILTER_STR,                       #Registers factory method for a FILTER
FILTER_AFUNC([SERVICE...])                      #AFUNC returns FUNC2(VAL[, ...]), which returns VAL2.

lower|uppercase(STR)                            #FILTER
json(OBJ[, NUM])                                #Calls JSON.sringify(OBJ, null, NUM). NUM is 2 by def.
                                                #Automatically used by {{EXPR}}
number(NUM[, NUM2])                             #FILTER that returns NUM as STR, with NUM2 decimals (def: 3), according to
                                                #current LOCALE.
                                                #If not NUM, returns ""
currency(NUM[, STR[, NUM2]])                    #FILTER that adds STR to end|beginning of a NUM, and return "" if not NUM.
                                                #NUM2 is number of decimals (def: 2)
date(DATE[, STR[, STR2]])                       #FILTER that returns DATE as STR3 according to format string STR which can 
                                                #also be:
                                                #  - "medium": "MMM d, y h:mm:ss a"
                                                #  - "short": "M/d/yy h:mm a"
                                                #  - "fullDate": "EEEE, MMMM d, y"
                                                #  - "longDate": "MMMM d, y"
                                                #  - "mediumDate": "MMM d, y" (déf)
                                                #  - "shortDate": "M/d/yy"
                                                #  - "mediumTime": "h:mm:ss a"
                                                #  - "shortTime": "h:mm a"
                                                #STR2 is timezone (def: locale)
format(STR, ARR|OBJ)                           |#If ARR, replace $NUM in STR by ARR[NUM]
                                               |#If OBJ, replace :VAR in STR by ARR.VAR
                                               |#MODULE "ui.format"
inflector(STR[, STR2])                         |#Change case/spaces according to STR2:
                                               |#  - "humanize" (def): One Two Three
                                               |#  - "underscore": one_two_three
                                               |#  - "variable": oneTwoThree
                                               |#MODULE "ui.inflector"
highlight(STR, STR2[, BOOL])                   |#Look for STR2 in STR and wrap it in <span class="ui-match">
                                               |#If BOOL true, case sensitive.
                                               |#Returns HTML as is, so must use ng-bind-html
                                               |#MODULE "ui.highlight"

linky(STR, STR2)                                #FILTER that wrap links (everything starting with a protocol) with
                                                #<a href="URL">...</a>, then use SANITIZE(STR2) (requires module ngSanitize)

                                  ┌──────────────┐
                                  │   SECURITY   │
                                  └──────────────┘

<any>                                           #Put ng-csp to bypass CSP restrictions (e.g. in Chrome extensions):
  ng-app ng-csp                                 #  - will be 30% slower
                                                #  - must also inlude angular-csp.css

$compileProvider.                               #When compiling, links in <a href="EXPR"> and <img src="EXPR"> are sanitized:
aHref|imgSrcSanitizationWhitelist([REGEXP])     #  - relative path -> absolute
                                                #  - if not match REGEXP (whitelist), prefixed with "unsafe:".
                                                #    Déf REGEXP: HTTP/HTTPS/FTP/FILE protocols (<a href> and <img src>), 
                                                #    data:image (<img src>) and mailto|tel (<a href>)

$sanitize                                       #From module ngSanitize.
SANITIZE(STR)                                   #Returns HTML code STR, with:
                                                #  - JavaScript code removed
                                                #  - links not matching COMPILEPROVIDER.aHref|imgSrcSanitizationWhitelist
                                                #    removed

$sce[Delegate]                                  #Sanitize web content.
                                                #Used by core features: 
                                                #  - SCE.HTML: ng-bind-html
                                                #  - SCE.RESOURCE_URL: ng-include, [ng-]src, templateUrl in MODULE.directive()
                                                #    and routeProvider.
                                                #  - <a href>, <img src> don't use it: see aHref|imgSrcSanitizationWhitelist()
                                                #Should be used by any code which inject links/HTML/CSS/JS.
                                                #Use $sce to execute, $sceDelegate to configure (through $sceDelegateProvider).
SCE[DELEGATE].getTrusted(CONTEXT, STR)          #According to CONTEXT:
                                                #  - SCE.CSS|URL|JS: throw exception
                                                #  - SCE.HTML: returns SANITIZE(STR)
                                                #  - SCE.RESOURCE_URL: throw exception if:
                                                #      - in SCEDELEGATEPROVIDER.resourceUrlBlacklist([VAL_ARR]) (déf: [])
                                                #        It is good idea to block redirect URL from own domain to other 
                                                #        domain, as other domain could be used to bypass security.
                                                #      - not in same domain, unless in 
                                                #        SCEDELEGATEPROVIDER.resourceUrlWhitelist([VAL_ARR]) (déf: ["self"])
                                                #      - VAL:
                                                #         - matches the whole URL
                                                #         - be careful, especially with REGEXP and **
                                                #         - can be:
                                                #            - STR: can use wildcards * (matches /[^:/.?&;]*/) and **
                                                #              (matches /.*/, to use only at end of URL, because in domain it 
                                                #              can be dangerous)
                                                #            - REGEXP: flags are ignored.
                                                #            - "self": same as CURRENT_PROTOCOL://CURRENT_DOMAIN/**
                                                #    Browse still does the same origin policy/CORS.
                                                #Can bypass this by using an OBJ instead of STR:
                                                #  - returned by SCE[DELEGATE].trustAs(CONTEXT, STR), which wraps it.
                                                #  - OBJ can be unwrap with SCE[DELEGATE].valueOf(CONTEXT, OBJ|STR), which 
                                                #    return underlying STR2 in OBJ, or as is if STR.
SCE.parseAs(CONTEXT, EXPR)                      #Like SCE.getTrusted(CONTEXT, $parse(EXPR))
SCE.isEnabled()                                 #If SCE can be used (déf: true)
                                                #Can be disabled with SCEPROVIDER.enabled([BOOL])


                                  ┌───────────────┐
                                  │   ANIMATION   │
                                  └───────────────┘

$animate                                        #Depends on ngAnimate module. If not included:
                                                #  - only perform the action (DOM/CSS) but not the temporary CSS classes 
                                                #    (.ng-animate, etc.) nor JavaScript handlers.
                                                #  - ANIMATE.animate() not dispo
                                                #Goal is to dissociate:
                                                #  - animation declaration:
                                                #     - DIRECTIVE calls ANIMATE.ANIMEVENT(...) which:
                                                #         - perform an action (DOM or CSS class manipulation)
                                                #         - temporarily adds some CSS classes during the manipulation:
                                                #            - in order: 
                                                #               1) .ng-animate
                                                #               2) .ng-ANIMEVENT        or .CLASS-add|remove 
                                                #               3) .ng-ANIMEVENT-active or .CLASS-add|remove-active
                                                #               4) then removes all three
                                                #            - transitions|animations:
                                                #               - must be performed from 2) to 2+3) (not only 3))
                                                #               - must consider the state before|after transitions to avoid
                                                #                 weird glitching
                                                #         - triggers JavaScript handlers registered with MODULE.animation()
                                                #     - enter|leave|move() only fire after SCOPE.$digest, but not 
                                                #       add|remove|setClass()
                                                #     - already defined in some core directives (especially enter|leave|move())
                                                #  - animation consumption:
                                                #     - in CSS, transitions/animations using temporary CSS classes
                                                #     - in JavaScript, MODULE register event handlers with MODULE.animation().
                                                #       Event handlers perform animation using e.g. JQ.animate(), etc.
                                                #Staggering:
                                                #  - if several siblings fire the same ANIMEVENT, instead of having animation
                                                #    on all of them at same time, can delay start of animation of one after
                                                #    the other according to a delay.
                                                #  - to do so, add (not remove any) a CSS rule with selector 
                                                #    .ng-ANIMEVENT-stagger (not .ng-ANIMEVENT nor .ng-ANIMEVENT-active) and 
                                                #    with property transition|animation-delay: TIME.
                                                #  - no support yet in JavaScript
                                                #Children:
                                                #  - wait for parent to finish animation, unless parent has directive
                                                #    ng-animate-children

ANIMATE.enter(AJQ, AJQ2, AJQ3[, CSS_OBJ])       #Append AJQ comme enfant de AJQ2, before sibling AJQ3 (null for last).
                                                #Uses .ng-enter[-active] on AJQ.
                                                #Returns PROMISE resolved when all animations are finished performing.
                                                #CSS_OBJ is CSS styles added during the action.
ANIMATE.move(AJQ, AJQ2, AJQ3[, CSS_OBJ])        #Similar but:
                                                #  - move AJQ
                                                #  - uses .ng-move[-active]
ANIMATE.leave(AJQ[, CSS_OBJ])                   #Similar but:
                                                #  - remove AJQ
                                                #  - uses .ng-leave[-active]
ANIMATE.add|removeClass(AJQ,CLASS_STR[,CSS_OBJ])#Similar but:
                                                #  - adds|remove CLASS_STR on AJQ
                                                #  - uses .CLASS_STR-add|remove[-active]
                                                #  - is alias to ATTRS.$add|removeClass(CLASS_STR)
ANIMATE.setClass(AJQ, CLASS_STR, CLASS2_STR     #Calls removeClass then addClass().
[, CSS_OBJ]                                     #Returns PROMISE resolved when all animations are finished performing.
ANIMATE.animate(AJQ, OBJ, OBJ2[, CLASS_STR]     #Similar as above but:
[, CSS_OBJ])                                    #  - use CLASS_STR (def: .ng-inline-animate) instead of .ng-ANIMEVENT[-active]
                                                #  - perform CSS transition from OBJ to OBJ2, e.g. 
                                                #     { color: "red" }, { color: "blue" }
ANIMATE.enabled([BOOL[, AJQ]])                  #Enable|disable animations.

ANIMATE.cancel(PROMISE)                         #Cancels an animation

$animateProvider                                #Only performs animations on elements whose class name matches REGEXP.
ANIMATEPROVIDER.classNameFilter(REGEXP)         #Done to decrease animation on low-performance devices.

MODULE.animation(CLASS_STR, AFUNC([SERVICE...]))#Register event handlers for ANIMATE.ANIMEVENT(AJQ, ...) for AJQ matching
                                                #CSS selector CLASS_STR (class selector only).
                                                #AFUNC returns { ANIMEVENT: FUNC(AJQ, ..., FUNC2) ... }, where FUNC:
                                                #  - is called when ANIMEVENT is fired
                                                #  - must perform the animation in JavaScript, e.g.:
                                                #    JQ.animate|effect|toggleClass|etc.(...)
                                                #  - must call FUNC2 when animation is done (async.)
                                                #  - must return FUNC3(BOOL), which is fired when animation stops, 
                                                #    BOOL being true if cancelled, false if normal end.
                                                #    Not always called if false.
                                                #    If cancelled and jQuery animation, should JQ.stop()
                                                #  - for add|removeClass ANIMEVENT:
                                                #     - only them can use CLASS2_STR
                                                #     - can be beforeANIMEVENT: same function, but before the actual action.

                                  ┌───────────────┐
                                  │   TEMPLATES   │
                                  └───────────────┘

<any>                                           #Same but:
  ng-bind-html="HTML_STR"                       #  - with HTML_STR, not a file
                                                #  - $sanitize HTML (must include ngSanitize)

<script type="text/ng-template" id="ID">        #Content (inline or through src="") can used as ID_STR, which will look like an
                                                #external HTML file, anywhere a partial template link is expected.
                                                #Can be in <body>

$templateCache                                  #template CACHE automatically filled in by any partial template used through
                                                #templateUrl STR (not template STR) (including directives) or <script>, and 
                                                #used afterwards.
                                                #Key is URL|ID
                                                #Value is ARR: NUM (status code), STR (content), OBJ (cache options), 
                                                #STR2 (status text)
$templateRequest(STR[, BOOL])                   #Calls URL STR, and fills $templateCache.
                                                #If error and BOOL false (def), throw errors.
GULP-NG-HTML2JS(OBJ)                            #Creates JavaScript file that loads MODULE that loads $templateCache with 
                                                #HTML_FILES. OBJ:
                                                #  - moduleName STR (déf: current file, i.e. one file/MODULE per HTML_FILE):
                                                #    if STR, use only one module for all, and gets the module instead of
                                                #    creating it.
                                                #  - rename FUNC(STR)->STR2: change template ID (déf: file relative path)
                                                #  - prefix|stripPrefix STR: same by prepending|substracting prefix
                                                #There is also a karma plugin karma-ng-html2js-preprocessor (but prefer Gulp)
GULP-ANGULAR-TEMPLATECACHE()                    #Essentially same as GULP-NG-HTML2JS (prefer later).

<ng-include>                                    #Applies a partial template. Creates a SCOPE. 
                                                #Uses enter and leave ANIMEVENT.
                                                #Uses SCE.RESOURCE_URL if ngSanitize is loaded.
  src="EXPR"                                    #Template is changed every time EXPR (which evaluates to URL_STR) is changed.
  onload="EXPR"                                 #Evaluated when a new partial template is loaded.
SCOPE.$on("$includeContentRequested|Loaded",    #Fired when content is going to be|is reloaded.
FUNC(AEVENT, URL))                              #Emitted from ng-include SCOPE.
SCOPE.$on( "$includeContentError", 
FUNC(AEVENT, URL))                              #Status 4** or 5**
<ui-include>                                   |#Same as <ng-include> except:
                                               |#  - no $includeContentRequested|Error event
                                               |#  - support HTML attribute fragment="SELECTOR", which filters partial template
                                               |#    to only matching parts.
                                               |#MODULE "ui.include". Requires jQuery.

                                  ┌─────────────┐
                                  │   ROUTING   │
                                  └─────────────┘

NAVIGATION ==>                                  #There are two ways URL is manipulated in order to reload the page:
                                                #  - HTML5 mode: AURL is the full path
                                                #      - must use a <base> URI if requireBase true (see below)
                                                #      - angularjs will use the HTML5 history API underneath.
                                                #      - Server must redirect all related AURL to underlying real file URL
                                                #      - Fires security exceptions with file:///
                                                #      - links are rewritten unless $locationProvider.rewriteLinks(false)
                                                #  - non-HTML5 mode: AURL is the hash part, excluding # + hashPrefix:
                                                #      - # is followed by an optional $locationProvider.hashPrefix(STR) 
                                                #        (déf: "", should use "!"), then a mandatory "/"
                                                #        e.g: URL/index.html#!/PATH/TO/FILE?VAR=VAL#HASH
                                                #      - Easier to setup, but not pretty URL.
                                                #      - must use <meta name="fragment" content="!"> for web crawlers.
                                                #Difference between both modes:
                                                #  - is in the interpretation of AURL, the "path" that is changed without 
                                                #    reloading the page, by $location and SERVICE depending on $location, like
                                                #    $route.
                                                #  - but not in the resolution of links. As a reminder in HTML:
                                                #      - absolute link are resolved as is
                                                #      - relative link starting with "/" are appended to hostname
                                                #      - otherwise, appended to base URI (déf: ".")
                                                #    For example, links with non-HTML5 mode must use #, while HTML mode links
                                                #    must look like real links.
                                                #  - so if HTML5 mode, will reload the page if $routeProvider not used
                                                #  - Decided by $locationProvider.html5Mode(BOOL|OBJ) where OBJ is:
                                                #     - enabled BOOL (déf: false). 
                                                #     - requireBase BOOL (def: true)
                                                #In HTML5 mode, there is a fallback to other mode when browser doesn't 
                                                #support it:
                                                #  - going to a relative link will convert it to hash version
                                                #  - everything else will be like non-HTML5 mode
                                                #  - so hashPrefix should always be set. 
                                                #AURL changes (combined with $routeProvider) (including parent DIR change in
                                                #HTML5 mode) doesn't reload page, but can:
                                                #  - Have a hash and search string.
                                                #  - Update history when changed, so can go backward/forward.
                                                #  - With routing, change current page and provide URL to come back to same 
                                                #    point ("deep linking").
                                                #  - For redirection, should change AURL then call LOCATION.replace()
                                                #Reload is still forced in those cases:
                                                #  - link using target="", including target="_self" (forced reload)
                                                #  - link pointing to different base URI
                                                #  - absolute links
                                                #  - changing URL manually (e.g. in omnibox or manual refresh) instead of 
                                                #    following a link
                                                #AURL is percent-encoded|decoded by getter|setters (except LOCATION.url(), but
                                                #not LOCATION.url(STR))

$location                                       #Gets URL/AURL, and sets AURL.
                                                #AURL changes apply once a $digest() is called.
                                                #Setters returns LOCATION.
LOCATION.absUrl()                               #Returns URL as STR
LOCATION.protocol()                             #Returns e.g. "http"
LOCATION.host()                                 #Returns e.g. "www.google.fr"
LOCATION.port()                                 #Returns e.g. 80. null if Unix socket.
LOCATION.url()                                  #Returns AURL
LOCATION.url(STR)                               #Sets AURL
LOCATION.path([STR])                            #Same without search string and hash.
LOCATION.hash([STR])                            #Same for hash in AURL
LOCATION.search()                               #Returns AURL GET variables as OBJ.
LOCATION.search(OBJ)                            #Replaces AURL GET variables by OBJ.
LOCATION.search(STR, VAL2)                      #Replaces AURL GET variable STR value by VAL2 (null to remove, true for no 
                                                #value)
LOCATION.replace()                              #Make current AURL changes replace history entry instead of adding new one.
                                                #Should call just after AURL change, before $digest()
LOCATION.state()                                #Manually get/set HTML5 history through pushState()/replaceState() (usually
LOCATION.state(OBJ)                             #not needed)
SCOPE.$on("$locationChangeStart|Success",       #Broadcasted from root SCOPE when AURL is about to change|is done.
FUNC(AEVENT, NEW_URL, OLD_URL))                 #Fired also at page load.

$anchorScroll                                   #SERVICE FUNC().
                                                #Emulate hash anchors with AURL (when $location.hash() changes, auto scoll).
                                                #Can be disabled with:
                                                #  - ANCHORSCOLLPROVIDER.disableAutoScrolling()
                                                #  - <ng-view|include autoscroll="BOOL_EXPR">
                                                #Adds extra scrolling (e.g. when there is a fixed header) with 
                                                #$anchorScroll = VAL, where VAL can be:
                                                #  - NUM|FUNC()->NUM (px)
                                                #  - AJQ: takes distance from top of page to AJQ bottom, using
                                                #    ELEM.getBoundingClientRect().bottom
                                                #    Must be position: fixed. Can e.g be fixed header.
                                                #In which case can be manually called as FUNC()
  
$route                                          #SERVICE to apply partial templates to <ng-view> according to AURL when it 
                                                #changes
ROUTE.current                                   #OBJ with members:
                                                #  - loadedTemplateUrl STR: URL of current partial template
                                                #  - locals OBJ: CONTROLLER arguments. Also contains special variables 
                                                #    $scope, and $template STR (initial uncompiled HTML code)
                                                #  - params OBJ: location.search()
                                                #  - pathParams OBJ: ROUTEPARAMS (see below)
                                                #  - scope SCOPE
ROUTE.updateParams(OBJ)                         #Modifies ROUTE.current.[path]params (must call $rootScope.$digest())
ROUTE.routes                                    #All routes defined by ROUTEPROVIDER, as an OBJ whose keys are the URL 
                                                #(null for otherwise()), and members are controller STR, originalPath STR,
                                                #regexp REGEXP, reloadOnSearch BOOL and templateUrl STR.
ROUTE.reload()                                  #Force reloading partial templates, which means:
                                                #  - ROUTEPROVIDER.when(...) are called
                                                #  - SCOPE and CONTROLLER in partial templates are reinitialized
SCOPE.$on("$routeChangeStart|Success",          #Broadcasted from root SCOPE when AURL is about to change|is done and 
FUNC(AEVENT, OLD_URL_OBJ, NEW_URL_OBJ))         #routing is gonna happen.
                                                #URL_OBJ has same members as ROUTE.current.
SCOPE.$on("$viewContentLoaded", FUNC(AEVENT))   #Emitted from <ng-view> SCOPE when a routing happened to it.

$routeProvider                                  #SERVICEPROVIDER, depending on ngRoute MODULE.
ROUTEPROVIDER.when(AURL, OBJ)                   #On $locationChangeStart AEVENT, does some actions on all <ng-view>, 
                                                #when current AURL is exactly AURL. 
                                                #Action depends on OBJ:
                                                #  - templateUrl URL|FUNC(OBJ): applies partial template URL (not a AURL, more 
                                                #    like a href attribute) to all children of <ng-view>
                                                #    FUNC(OBJ) must return URL_STR, and OBJ are the ROUTEPARAMS
                                                #  - template STR|FUNC(OBJ): same with a STR
                                                #  - redirectTo STR|FUNC(OBJ, STR2, OBJ2): changes current AURL.
                                                #    "" means no change of AURL.
                                                #    FUNC(OBJ) must return URL_STR, and OBJ are the ROUTEPARAMS, STR2 
                                                #    $location.path() and OBJ2 $location.search()
                                                #  - controller CONTROLLER_STR|AFUNC: use CONTROLLER in partial template.
                                                #  - resolve OBJ: pass each VAR of { VAR:VAL ... } as potential argument to 
                                                #    CONTROLLER AFUNC. VAL can be:
                                                #      - SERVICE_STR 
                                                #      - SERVICE AFUNC, which can return:
                                                #        - a normal VAL
                                                #        - a PROMISE: $location will be changed only once PROMISE is 
                                                #          resolved (and not if rejected), and final VAL will be the one used
                                                #          in resolve(VAL)
                                                #          If rejected, fires SCOPE.$on("$routeChangeError", 
                                                #          FUNC(AEVENT, OLD_URL_OBJ, NEW_URL_OBJ) broadcasted from root SCOPE.
                                                #          Make the page change once some async. work has been performed.
                                                #  - reloadOnSearch BOOL: if false (déf: true), doesn't do anything if 
                                                #    only $location.search() or $location.hash() was changed, except firing 
                                                #    SCOPE.$on("$routeUpdate", FUNC(AEVENT, NEW_URL_OBJ)) broadcasted from
                                                #    root SCOPE.
                                                #  - caseInsensitiveMatch BOOL (déf: false): for AURL
                                                #AURL:
                                                #  - can contain:
                                                #     - :VAR, meaning anything up until the next / or . will be stored in VAR, 
                                                #       which can be accessed through ROUTEPARAMS.VAR.
                                                #     - :VAR*: same but is not stopped by next /
                                                #     - :VAR*? or :VAR?: same but can be empty (otherwise cannot)
                                                #  - can be used as SERVICE $routeParams.VAR, refering to :VAR (see above) or 
                                                #    to any current AURL GET variable in:
                                                #      - controller AFUNC above (next $routeParams, after AURL change)
                                                #      - resolve SERVICE AFUNC (current $routeParams, before AURL change)
                                                #Returns ROUTEPROVIDER.
ROUTEPROVIDER.otherwise(STR|OBJ)                #Same when no AURL matches. 
                                                #STR is same as { redirectTo: STR }
                                                #Good idea to put one with redirectTo: to avoid wrong AURL (although user can
                                                #bypass it by forcing page reload).

<any>                                          |#Sets VAR BOOL === whether STR matches LOCATION.path():
  ui-route[="STR"]                             |#  - VAR is ng-model="VAR", or route-model="VAR", or SCOPE.$uiRoute
                                               |#  - STR is [ng-]href value by def.
                                               |#  - If [ng-]href, "matches" means STR is included in LOCATION.path()
                                               |#    Otherwise it is /^REGEXP_STR$/i
                                               |#MODULE "ui.route"

<ng-view>                                       #Uses enter and leave ANIMEVENT. Creates a SCOPE.
  onload="EXPR"                                 #Fires EXPR in current SCOPE everytime ng-view changes



UI ROUTER ==>                                  ##MODULE "ui.router". Version 0.2.13
UI-ROUTER-EXTRAS ==>                          ###Plugin to UI-router. MODULE "ct.ui.router.extras". Version 0.0.13

STATES ==>                                     ##Provides states:
                                               ##  - current place in the UI
                                               ##  - associated with STATE_CONF, i.e. actions fired when this state or a 
                                               ##    children is on.
                                               ##  - has a name STATE_STR

STATES HIERARCHY ==>                           ##States can have children:
                                               ##  - noted "[STATE][.SUBSTATE]":
                                               ##     - STATE can be omitted to mean current one
                                               ##     - STATE can "^" to mean parent one
                                               ##     - can also specify STATE_CONF.parent STATE_STR|CONF instead, which will
                                               ##       make SUBSTATE_STR relative to STATE_STR (i.e. writing "SUBSTATE" 
                                               ##       instead of "STATE.SUBSTATE")
                                               ##  - the states hierarchy corresponds to the hierarchy of <ui-view> containing
                                               ##    each other: when an <ui-view> contains another one, the other one is 
                                               ##    activated by the substate.
                                               ##  - each SUBSTATE inherits from parent (but can be overwritten): 
                                               ##     - STATE_CONF.data|resolve 
                                               ##     - STATE_CONF.url (prepends parent AURL, unless starts with "^")
                                               ##     - STATE_PARAM is inherited. However documentation says it is not and 
                                               ##       that STATE_CONF.resolve must be used to fix this
                                               ##  - a SUBSTATE can modify a parent state with STATE_CONF.views.VIEW@STATE
                                               ##    (see below)

TABS ==>                                       ##To implement tabs, use:
                                               ##  - tab: 
                                               ##      li(ng-class="{ active: $state.includes('STATE') }")
                                               ##        a(ui-sref="STATE")
                                               ##  - content: one <ui-view> content sibling for each tab, with:
                                               ##      ng-show="$state.includes('STATE')"
                                               ##And use sticky + deepStateRedirect

AURL BINDING ==>                               ##Using STATE_CONF.url:
                                               ##  - AURL and state are bound: changing one updates the other.
                                               ##  - STATE_PARAM are bound according to either:
                                               ##     - AURL pattern (optional always, defaults to ""), including in query 
                                               ##       string:
                                               ##        - *VAR: up to end
                                               ##        - :VAR or {VAR}: up to next /
                                               ##        - ?VAR or &VAR: same as ?{VAR} or &{VAR}
                                               ##        - {VAR:REGEXP_STR} (e.g. {VAR:[0-9]*})
                                               ##        - {VAR:TYPE} (e.g. {VAR:int})
                                               ##  - STATE_PARAM is accessible via $stateParams SERVICE (preferred) or 
                                               ##    STATE.params. 
                                               ##  - "STATE({ VAR: STR_EXPR })" allows to specify STATE_PARAM in STATE_STR
$urlMatcherFactoryProvider.caseInsensitive(BOL)##Changes whether AURL patterns are case insensitive (def: false)
$urlMatcherFactoryProvider.strictMode(BOOL)    ##Changes whether trailing slashes in AURL patterns matters (def: true)
$urlMatcherFactoryProvider.type                ##Creates a new TYPE. OBJ[2] are same (they are merged), except OBJ2 is done 
(TYPE_STR, OBJ|FUNC()->OBJ[,OBJ2|FUNC()->OBJ2])##when Angular first compiles. OBJ[2]:
                                               ##  - encode(VAL[, VAR_STR])->STR: from real type to STR
                                               ##  - decode(STR[, VAR_STR])->VAL: inverse
                                               ##  - is(VAL[, VAR_STR])->BOOL: whether it is of the right type
                                               ##  - equals(VAL, VAL2)->BOOL
                                               ##  - pattern REGEXP
                                               ##Example: providing an ENUM, which translates as an ID in the AURL.
STATE.href(STATE_STR|CONF[, STATE_PARAM[,OBJ]])##Returns state as a AURL. OBJ:
                                               ##  - inherit, relative: like STATE.go()
                                               ##  - absolute BOOL (def: false): whether it is absolute URL or relative AURL
                                               ##  - lossy BOOL: if true (def), and no AURL can be provided, returns first
                                               ##    possible parent AURL

STATEPROVIDER.state(STATE_STR, STATE_CONF)     ##Creates a STATE_CONF, associated with name STATE_STR.
                                               ##STATE_CONF can be:
                                               ##  - views.VIEW[@STATE] STATE_CONF_OBJ: for <ui-view> with name VIEW.
                                               ##    @STATE (def: current state) allows a SUBSTATE to modify a parent STATE.
                                               ##    STATE_CONF.url must be specified outside views OBJ, as sibling
                                               ##  - STATE_CONF_OBJ: same as views."" STATE_CONF_OBJ
                                               ##STATE_CONF_OBJ:
                                               ##  - template HTML_STR|FUNC(STATE_PARAM)->HTML_STR: fills in <ui-view>
                                               ##  - templateUrl AURL|FUNC(STATE_PARAM)->AURL: similar
                                               ##  - templateProvider AFUNC()->HTML_STR|PROMISE
                                               ##  - controller CONTROLLER_STR|AFUNC: to fire. Must define template* too.
                                               ##  - controllerAs CONTROLLER_STR: rename controller
                                               ##  - controllerProvider AFUNC()->CONTROLLER_STR|AFUNC
                                               ##  - resolve.VAR SERVICE[_STR]|AFUNC()->PROMISE: allow to use SERVICE VAR
                                               ##    (or PROMISE resolved value) in controller*
                                               ##  - url AURL (def: autoconstructed): see above
                                               ##  - parent STATE_STR|CONF: see above
                                               ##  - abstract BOOL (def: false): if true, can never be active, but its child
                                               ##    states can be. Good for sibling states to share resolve, data, url,
                                               ##    template, etc. but with necessity to show them not bare parent.
                                              ###  - sticky BOOL (def: false): if true, keep state opened (meaning e.g. $state
                                              ###    and controllers not reinitialized) as long as navigating in its children,
                                              ###    siblings or siblings children
                                              ###  - deepStateRedirect BOOL|OBJ (def: false): if true, when navigating away
                                              ###    from state or its children, remembers current state/substate on. When 
                                              ###    navigating back, return to that one remembered.
                                              ###    Can also specify OBJ:
                                              ###     - default DOBJ, with members state STATE_STR, params STATE_PARAM: when no
                                              ###       state remembered, redirect to that one
                                              ###     - params BOOL|STR_ARR: remembers several states, according to STATE_PARAM
                                              ###       If STR_ARR, only use variables STATE_PARAM.STR (otherwise any)
                                              ###     - AFUNC()->BOOL|DOBJ: whether to redirect or not. 
                                              ###       Can use SERVICE $dsr$ OBJ.redirect|to DOBJ (current|next DOBJ)
                                               ##  - onEnter|Exit AFUNC
                                               ##  - reloadOnSearch BOOL: if true (def), reload states if only query variable
                                               ##    or fragment changed. Seems always false though.
                                               ##  - data OBJ: arbitrary data
                                               ##  - params OBJ: defines default STATE_PARAM. OBJ.VAR:
                                               ##     - value VAL|FUNC()->VAL: default value
                                               ##     - array BOOL: by def, ?VAR=VAL -> VAL, but ?VAR=VAL&VAL2 -> [ VAL, VAL2 ]
                                               ##     - squash BOOL|STR: when value is same as default value:
                                               ##        - false: nothing special
                                               ##        - true: omitted
                                               ##        - STR: replaced by STR
                                               ##       Only changes STATE_PARAM in URL, not in actual STATE_PARAM object
                                               ##       Default value is defined by
                                               ##       $urlMatcherFactoryProvider.defaultSquashPolicy(STR) where STR is
                                               ##       "nosquash" (def), "slash" or STR, for false|true|STR
                                               ##    OBJ.VAR: VAL is shorthand for OBJ.VAR: { value: VAL }

$futureStateProvider                          ###Allows defining STATE_CONF at runtime.
FUTURESTATEPROVIDER.futureState(FSTATE)       ###FSTATE:
                                              ###  - stateName STATE_STR
                                              ###  - url URL
                                              ###  - type TYPE_STR
                                              ###Binds a state to URL, and fire AFUNC registered with 
                                              ###FUTURESTATEPROVIDER.stateFactory(TYPE_STR, AFUNC), where AFUNC:
                                              ###  - must either:
                                              ###     - (sync) register STATE_STR with $stateProvider.state(STATE_CONF)
                                              ###     - (async) return PROMISE resolving to STATE_CONF
                                              ###  - can use SERVICE futureState FSTATE
FUTURESTATEPROVIDER.addResolve
(AFUNC()->PROMISE)                            ###Will hold any futureState() resolution until PROMISE is resolved.

$previousState                                ###Remembers states to come back to it later. Experimental so not documented yet.


<ui-view>                                      
  name="VIEW"                                  ##Like <ng-view> (including Angular transitions) but for $stateProvider, except:
  autoscroll="EXPR"                            ##  - name (def: ""): can have several <ui-view> per page. 
  onload="EXPR"                                ##    See $stateProvider.views
STATE.$on("$viewContentLoaded",                ##  - $viewContentLoaded: extra argument STATE_CONF
FUNC(AEVENT, STATE_CONF))                      ##  - children are default content while loading

$uiViewScroll                                  ##SERVICE, overriding $anchorScroll
UIVIEWSCROLL(AJQ)                              ##Scroll to AJQ
UIVIEWSCROLLPROVIDER.useAnchorScroll()         ##Use $anchorScroll instead

<a>
  ui-sref="STATE_STR"                          ##Generates href="" according to STATE_CONF_OBJ.url
  ui-sref-opts="OBJ_EXPR"                      ##Passed to STATE.go() OBJ
<any>                                          ##Add/remove CLASS depending on current element or any child element ui-sref 
  ui-sref-active="CLASS[ ...]"                 ##STATE being active. Used to highlight menu items.
  ui-sref-active-eq="..."                      ##Same but only on current element.

$state                                         ##SERVICE
STATE.current                                  ##STATE_CONF
STATE.get()                                    ##Returns all STATE_CONF_ARR
STATE.get(STATE_STR[, STATE_STR2])             ##Returns STATE_CONF (relative to STATE_STR2 (def: current one))
STATE.params                                   ##STATE_PARAM
STATE.transition                               ##PROMISE returned by last STATE.transitionTo(), or null
STATE.transitionTo(STATE_STR[, STATE_PARAM     ##Changes state. Returns PROMISE:
[, OBJ]])                                      ##  - success(STATE_CONF)
                                               ##  - failure("transition STR"), where STR can be:
                                               ##     - superseded: another transition started 
                                               ##     - prevented: EVENT.preventDefault() in $stateChangeStart
                                               ##     - aborted: EVENT.preventDefault() in $stateNotFound
                                               ##     - prevented: cannot found state
                                               ##OBJ:
                                               ##  - location BOOL|"replace": if true (def), updates AURL. 
                                               ##    If "replace", also update history.
                                               ##  - inherit BOOL (def: false): if true, merge STATE_PARAM with current
                                               ##    STATE_PARAM2 coming from common ancestor
                                               ##  - relative STATE_STR (def: none): what "^" refers to
                                               ##  - notify BOOL: if true (def), fires stateChange* events
                                               ##  - reload BOOL: if false (def), does not reload if STATE_CONF and STATE_PARAM
                                               ##    are same
STATE.go(...)                                  ##Higher-level (should be preferred), similar to transitionTo(), except:
                                               ##  - inherit def to true, relative def to parent STATE_CONF
STATE.includes|is(STATE2_STR[, STATE_PARAM2    ##Checks if STATE2 is same [or parent] of STATE, and if STATE_PARAM2 are in
[, OBJ]])                                      ##current STATE_PARAM
                                               ##STATE2_STR can include globbing * and ** (between dots)
                                               ##OBJ: relative: like STATE.transitionTo()
includedByState|isState(STATE2_STR)            ##Like STATE.includes|is(STATE2_STR) but as FILTER
STATE.reload()                                 ##But do not fire events again. 
                                               ##Returns same PROMISE as go()
$rootScope.
$on("$stateChangeStart|Success|Error", 
FUNC(AEVENT, NEW_STATE_CONF, NEW_STATE_PARAM,
OLD_STATE_CONF, OLD_STATE_PARAM[, ERROR]))     ##
$rootScope.$on("$stateNotFound", 
FUNC(AEVENT,OBJ,OLD_STATE_CONF,OLD_STATE_PARM))##OBJ: to NEW_STATE_CONF, toParams NEW_STATE_PARAM, options OBJ2 (from go())

$urlRouterProvider.when(STR|REGEXP, AURL|AFUNC)##Similar to $routeProvider: redirects to AURL or fires AFUNC if AURL changed
$urlRouterProvider.otherwise                   ##to STR|REGEXP: 
(AURL|FUNC($injector, $location)->URL)         ##  - not when AURL changed through state change.
                                               ##  - STR can contain URL pattern same as for states
                                               ##AFUNC:
                                               ##  - can use SERVICE $match with current STATE_PARAM, according to URL pattern
                                               ##  - can return AURL, false (means try another $urlRouterProvider.when()) or
                                               ##    nothing (means stop here)
                                               ##STATE_CONF.url calls this to sync AURL and STATE, so no need to call ourselves
                                               ##for that reason. However can use for other reasons, i.e. AURL redirections or
                                               ##defining a default redirection to home page with otherwise()
$urlRouterProvider.rule                        ##Transform AURL ($location.path()) before passing it to 
(FUNC($injector, $location)->AURL)             ##$urlRouterProvider.when()
                                               ##Recursively called until result remain the same, so should be indempotent.

                                  ┌───────────┐
                                  │   FORMS   │
                                  └───────────┘

GOAL ==>                                        #Separate model from view:
                                                #  - link but dissociate $viewValue from $modelValue.
                                                #    Use filtering functions ($parsers and $formatters) for both of them.
                                                #  - automatically updates dirtiness/validity on model, letting view use 
                                                #    CSS classes

FORMCONTROLLER AND NGMODELCONTROLLER ==>        #Goal:
                                                #  - can access dirtiness/validity in any EXPR.
                                                #    Can be combined with ng-show|hide to display error messages when invalid.
                                                #  - Can create a DIRECTIVE using NGMODELCONTROLLER (with require: "ngModel")
                                                #    in order to access utility methods to change behavior:
                                                #      - implement custom validity: add one function to $parsers and 
                                                #        $formatters
                                                #      - implement custom behavior: redefine $render() and call $setViewValue 
                                                #        on both DOM events (e.g. "blur") and at compile time (in the 
                                                #        directive, to init the $viewValue and $modelValue)

<form>                                          #Automatically:
  novalidate                                    #  - adds CSS dynamic classes (use add|removeClass ANIMEVENT):
                                                #     - ng-pristine|dirty: whether user has changed it at least once.
                                                #       Useful to put CSS rule on .ng-invalid-required with .ng-dirty, so that
                                                #       it doesn't show as invalid in the beginning.
                                                #     - ng-[un]touched: whether user has focus in then out at least once.
                                                #     - ng-[in]valid: Validity status
                                                #        - ng-[in]valid-VALIDTYPE: additional info on validity status for a 
                                                #          specific VALIDTYPE (dash-type, not camelcase)
                                                #        - sets up validity checks (even with no native browser support)
                                                #          Good idea to disable native one (INPUT.validity.valid) with 
                                                #          novalidate
                                                #     - parent FORM inherit them, and they are inherited from children 
                                                #       controls (which use ng-model).
                                                #  - adds a special CONTROLLER, FORMCONTROLLER, available under
                                                #    SCOPE.NAME, where NAME is <form> name. Doesn't create a new SCOPE.
                                                #  - it is a good idea not to have action attribute (<form action="">) but
                                                #    define ngSubmit handler instead, to check validation client-side before
                                                #    sending the request.
FORMCONTROLLER.$setDirty|Pristine()
FORMCONTROLLER.$dirty|pristine                  #Setters/getters of ng-pristine|dirty. Doesn't propagate to children.
FORMCONTROLLER.$set[Unt|T]ouched()              
FORMCONTROLLER.$[un]touched                     #Same for ng-[un]touched
FORMCONTROLLER.$setValidity(VALIDTYPE_STR, BOOL,#Same for ng-[in]valid.
CONTROL)                                        #VALIDTYPE is validity type, among "required", "email", "url", "number",
FORMCONTROLLER.$[in]valid                       #"pattern", "min|max[length]"
                                                #If false, $modelView will be set to undefined, unless ng-model-options 
                                                #OBJ.allowInvalid true
                                                #Called by NGMODELCONTROLLER.$validate(), which is used natively by 
                                                #<input type="email|url|number">, <input required>, etc.
FORMCONTROLLER.$error                           #{ VALIDTYPE_STR: NGMODELCONTROLLER_ARR ... } of all invalid children controls
FORMCONTROLLER.setSubmitted()
FORMCONTROLLER.$submitted                       #Whether the form was submitted
FORMCONTROLLER.$add|removeControl(CONTROL)      #Add|removes CONTROL to FORM (automatically done at compile time with ng-model)

<input|select|textarea>                         #Does several things:
  ng-model=VAR                                  #  - Updates VAR on current SCOPE according to value attribute:
                                                #     - Provides two-way data binding: 
                                                #        - not only VAR can be changed in SCOPE and view will be updated 
                                                #          (already the case)
                                                #        - but also the contrary
                                                #     - when $viewValue changes, can update $modelValue after specific 
                                                #       delay|event instead with ng-model-options=OBJ_EXPR, where OBJ:
                                                #         - updateOn "EVENT[ ...]"
                                                #         - debounce NUM: after NUMms, or { EVENT: NUM ... }
                                                #     - if ng-model-options time|event delay is pending, can:
                                                #        - FORM|NGMODELCONTROLER.rollbackViewValue(): $viewValue -> $modelValue
                                                #        - FORM|NGMODELCONTROLER.commitViewValue(): $modelValue -> $viewValue
                                                #     - if ng-model-options OBJ.getterSetter true, use:
                                                #        - get VAR() instead of VAR
                                                #        - set using VAR(VAL) instead of VAR = VAL
                                                #  - adds CSS dynamic classes ng-pristine|dirty, ng-[in]valid and 
                                                #    ng-[un]touched: see <form>
                                                #  - validity: see <form>
                                                #  - creates special CONTROLLER NGMODELCONTROLLER on current element, 
                                                #    available under FORMCONTROLLER.NAME, where NAME is element name.
NGMODELCONTROLLER.$setDirty|Pristine()
NGMODELCONTROLLER.$dirty|pristine                  
NGMODELCONTROLLER.$set[Unt|T]ouched()
NGMODELCONTROLLER.$[un]touched
NGMODELCONTROLLER.$setValidity(VALIDTYPSTR,BOOL)
NGMODELCONTROLLER.$[in]valid                       
NGMODELCONTROLLER.$error                        #Like FORMCONTROLLER
NGMODELCONTROLLER.$view|modelValue              #viewValue is the view CONTROL.value, modelValue the SCOPE.VAL.
                                                #modelValue goes through $parsers first.
NGMODELCONTROLLER.$parsers|formatters           #FUNC(VAL)_ARR: when setting $view|modelValue, it is passed through each 
                                                #function (returning VAL2), which will:
                                                #  - change it (e.g. return undefined if bad formatting)
                                                #  - do actions (e.g. call $setValidity())
                                                #$parsers is fired when $viewValue is updated (e.g. user UI action), and it 
                                                #manipulates $modelValue only.
                                                #$formatters is inverse: fired when $modelValue is updated (i.e. SCOPE.VAR then
                                                #$digest()), and it manipulates $viewValue only.
NGMODELCONTROLLER.$setViewValue(VAL)            #Emulates setting $viewValue with UI action.
                                                #Must call SCOPE.$digest() after.
                                                #Updates CSS classes for dirtyness
                                                #Doesn't update view: use $render()
NGMODELCONTROLLER.$render()                     #Updates view according to $viewValue
NGMODELCONTROLLER.$isEmpty(VAL)                 #Returns true if VAL is considered empty.
NGMODELCONTROLLER.$viewChangeListeners          #FUNC()_ARR: event listeners on view value changes
NGMODELCONTROLLER.$name                         #HTML name attribute of the ELEM

NGMODELCONTROLLER.$validate()                   #Calls each $[async]validators.VAR, which updates
                                                #NGMODELCONTROLLER.setValidity(VAR, BOOL)
                                                #$validators are called before $asyncValidators
                                                #Adds FORMCONTROLLER|NGMODELCONTROLLER.$pending.VAR FUNC() and CSS class
                                                #.ng-pending while async validation is on.
NGMODELCONTROLLER.$[async]validators.VAR        #FUNC($modelValue, $viewValue)->BOOL|PROMISE


<input|textarea>
  ng-min|maxlength="NUM"                        #Validation. If -1 (maxlength), disables.
  ng-pattern="STR"                              #Validation, where STR is a "/REGEXP/" (including slashes).
                                                #Empty value is valid.
  ng-change="EXPR"                              #Evaluates EXPR when modelValue (not viewValue) changes.

<input type="text">
  ng-trim="BOOL"                                #If true (déf), automatically trim modelValue and viewValue.
  ng-list[="STR"]                               #Converts $modelValue to a STR_ARR using delimiter STR (déf: ", ")
  ui-mask="STR"                                |#Forces user input according to STR and ANGULAR.value()
                                               |#uiMaskConfig.maskDefinitions OBJ2 (def: { "9": /0-9/, "A": /[a-zA-Z]/, 
                                               |#"*": /[a-zA-Z0-9]/ })
                                               |#  - each user input must match each STR character REGEXP
                                               |#  - STR character can be followed by "?" (means optional)
                                               |#  - if STR character not a OBJ2 key, means:
                                               |#     - not part of user input (forced)
                                               |#     - always displayed on input
                                               |#     - part of $viewValue, but not $modelValue
                                               |#  - sets up $setValidity()
                                               |#  - can use a placeholder="..." showing the pattern
                                               |#If uiMaskConfig.clearOnBlur BOOL true (def), removes user input on blur event
                                               |#if not fully complete.
                                               |#Requires ng-model
                                               |#MODULE "ui.mask"
  ui-reset[="STR"]                             |#Wraps <input> (requires ng-model) in span.ui-resetwrap, and appends as next
                                               |#sibling a.ui-reset, with a click handler erasing <input> value, and putting
                                               |#STR instead, or ANGULAR.value() uiResetConfig (def: "")
                                               |#Must add CSS to control a.ui-reset appearance.
                                               |#MODULE "ui.reset"


<input type="checkbox">                         #Checkboxes using ng-model="VAR" binds VAR to:
  ng-true|false-value="EXPR"                    #  - true|false if not using ng-true|false-value
                                                #  - EXPR otherwise
  ng-indeterminate="EXPR"                      |#Assigns to ELEM.indeterminate, i.e. will show horizontal bar if EXPR non-empty
                                               |#MODULE "ui.indeterminate"

<input type="radio">                            #All radio buttons of the same group must have same ng-model VAR.
  ng-value="EXPR"                               #VAR will be set according to value="STR"
                                                #ng-value="EXPR" is same as value="{{EXPR}}", except return type of EXPR is
                                                #not transtyped to STR.

<input type="number|date[TimeLocal]|            #modelValue is a NUM|DATE. DATE timezone (def: locale) can be changed with
  time|week|month">                             #ng-model-options OBJ.timezone (only "UTC" supported besides def.)
  min|max="NUM|DATE"                            #Validation. 
                                                #Also constraints the arrows, and puts some popup when manually entering it
                                                #beyond the min|max.

<select>                                        #Populates <select> with <option> (prefer to ng-repeat).
  ng-options="..."                              #Removes current ones, except default one ("" value).
                                                #"..." is "[EXPR as] EXPR2 [disable when BOOL_EXPR6] [group by EXPR3] 
                                                #for EXPR4 in ARR|OBJ [track by EXPR5]", where:
                                                #  - ARR|OBJ is the list of <option> to include
                                                #  - EXPR4 is VAL_VAR for ARRAY, ( KEY_VAR, VAL_VAR ) for OBJ, where the VAR 
                                                #    can be used in other parts of the expression
                                                #  - EXPR2 is the <option> label
                                                #  - EXPR is the modelValue used for this <option> (déf: EXPR4)
                                                #  - EXPR3 put elements with same EXPR3 into the same <optgroup>
                                                #  - EXPR5 returns an ID, to remove duplicates
                                                #  - if EXPR6 true, make <option> disabled
                                                #Ex: 
                                                #  OBJ.result as OBJ.uiname group by OBJ.category for OBJ in
                                                #  [ { result NUM, uiname STR, category STR } ... ]

<any>                                          |#Quick way to set up Angular validity.
  ui-validate="STR|OBJ_EXPR"                   |#For each key in OBJ_EXPR { KEY: STR_EXPR }:
                                               |#  - STR_EXPR returns BOOL, or PROMISE returning BOOL
                                               |#  - adds to $formatters and $parsers a function calling 
                                               |#    $setValidity(KEY_STR, BOOL) accordingly
                                               |#  - Can trigger this function on watching an aditional EXPR using 
                                               |#    ui-validate-watch="EXPR" (useful if BOOL does not depend only on ng-model)
                                               |#     - EXPR can be STR_EXPR, EXPR_ARR or { KEY: STR_EXPR|EXPR_ARR }
                                               |#  - STR_EXPR can use $value for current value
                                               |#STR_EXPR is like OBJ_EXPR { validity: STR_EXPR }
                                               |#MODULE "ui.validate"

                                  ┌──────────┐
                                  │   AJAX   │
                                  └──────────┘

$httpBackend                                    #SERVICE FUNC, underlyingly used by $http. 
                                                #Should not be used as is. Only used to provide mocks.
HTTPBACKEND(METHOD, URL, DATA, CALLBACK, 
HEADERS, TIMEOUT, WITHCREDENTIALS, RESPONSETYPE)#

$http                                           #SERVICE FUNC, similar to JQ.ajax()
HTTP[.METHOD](OBJ)                              #Effectue une request AJAX, where OBJ has members:
                                                #  - url STR
                                                #  - method STR (e.g. "GET")
                                                #  - params OBJ: GET variables. Can be { VAR: STR|OBJ2 }, where OBJ2 is 
                                                #    percentage-escaped.
                                                #  - data VAL: data sent from client to server.
                                                #    Can be STR|OBJ (OBJ is JSON'd) or other things by changing 
                                                #    transformRequest
                                                #  - headers { VAR: STR|FUNC(OBJ)->STR ... }
                                                #  - cache BOOL|CACHE: use a CACHE if method is GET or JSONP
                                                #    If true, use HTTP[PROVIDER].defaults.cache CACHE if defined, or "$http" 
                                                #    CACHE. 
                                                #    If false (déf), doesn't use cache.
                                                #    What's cached is [status, data, headers] with key being the URL.
                                                #  - transformRequest|Response FUNC[_ARR]: replace default
                                                #    transformRequest|Response (cf below)
                                                #  - xsrfCookieName STR, xsrfHeaderName STR2: override default ones
                                                #Returns a PROMISE:
                                                #  - success|error callback is FUNC(OBJ2), where OBJ2 has members:
                                                #     - data VAL: response
                                                #       Can be STR|OBJ (OBJ is unJSON'd) or other things by changing 
                                                #       transformResponse
                                                #     - status UINT. Status code is 0 if request could not be sent 
                                                #       (e.g. Same origin policy)
                                                #     - statusText STR
                                                #     - headers FUNC([STR]): return response headers as OBJ3
                                                #     - config: OBJ used in HTTP(OBJ)
                                                #  - with special members:
                                                #     - success FUNC(CALLBACK(STR, UINT, FUNC2, OBJ)): same as 
                                                #       PROMISE.then(OBJ2), but with the four OBJ2 members 
                                                #     - error: same for error callback
HTTP[PROVIDER].defaults                         #Default value for:
                                                #  - headers { METHOD: { VAR: STR ... } }, where METHOD can be "common" for all
                                                #  - transformRequest|Response FUNC(VAL, OBJ, NUM)_ARR:
                                                #     - chain of FUNC() called on data (sent from client, and received from
                                                #       server) to modify it (must return it).
                                                #       Can be augmented to process data sent|received, add new types, etc.
                                                #     - VAL is response, OBJ headers, NUM status
                                                #     - transformRequest final output must be STR, and transformResponse 
                                                #       initial input will be STR
                                                #     - Default ones:
                                                #        - transformRequest: serialize JSON when it is an OBJ 
                                                #        - transformResponse: unserialize JSON when STR seems to be an OBJ
                                                #          If JSON contains exactly ")]}',\n" first (good idea from server to
                                                #          protect against vulnerability), strip it first.
                                                #  - xsrfCookieName STR, xsrfHeaderName STR2:
                                                #     - XSRF prevention
                                                #     - If cookie called STR present (déf: "XSRF-TOKEN"), will send its value
                                                #       in STR2 header (déf: "X-XSRF-TOKEN")
                                                #     - So server must send "XSRF-TOKEN" cookie with authentication data hashed
                                                #       with salt, then client requests will always send this secret,
                                                #       preventing injected XSRF requests
                                                #     - Doesn't work for CORS requests
HTTPPROVIDER.interceptors                       #SERVICE_STR|AFUNC_ARR, used to modify config OBJ (used in HTTP(OBJ)). Déf: []
                                                #SERVICE OBJ has members:
                                                #  - request FUNC(OBJ), returning OBJ2.
                                                #    Can also return a PROMISE, which must be resolved with OBJ2.
                                                #  - requestError FUNC(OBJ2): called if the request FUNC of a previous
                                                #    interceptors (not same index in the SERVICE_ARR) has throw an OBJ2 or
                                                #    be rejected with OBJ2. 
                                                #    Must return an OBJ3|PROMISE like request FUNC.
                                                #  - response[Error]: same with OBJ { data, status, headers, config } returned
                                                #    in response.

SERVER SECURITY ==>                             #  - when sending JSON back, must include ')]}',\n' (cf plus hat)
                                                #  - URL with side-effect must check a XSRF token, and others must initialize
                                                #    it (by sending a cookie)

$resource                                       #SERVICE FUNC from module ngResource
                                                #Provides abstraction over $http to communicate with REST API returning 
                                                #JSON element.
RESOURCE                                        #Returns RSRC_OBJ with RSRC_OBJ.ACTION([ARG_OBJ3, ][POST_OBJ]).$promise:
(URL[,ARG_OBJ1[,{ACTION:HTTPOBJ ...}[, OBJ2]]]))#  - if only one OBJ given, is POST_OBJ unless GET method
                                                #  - fires $HTTP(HTTPOBJ) with URL, where HTTPOBJ also has members 
                                                #    params ARG_OBJ2
                                                #  - returns PROMISE:
                                                #     - resolved with BRSRC_OBJ: same as RSRC_OBJ, but use $ACTION(...) instead
                                                #       of ACTION(...).$promise, and cannot use POST_OBJ
                                                #     - RSRC_OBJ can be bound to SCOPE.VAR which is bound to view model and 
                                                #       view will update once ACTION is resolved.
                                                #     - error passes same OBJ as $HTTP error callback, with data.error ERROR
                                                #  - populates RSRC_OBJ.VAR with the JSON response
                                                #    If response is array, use HTTPOBJ.isArray true, to return RSRC_OBJ_ARR
                                                #  - ARG_OBJ
                                                #     - if { VAR: "@VAR2" }: will use VAR: RSRC_OBJ.VAR2 as POST variable,
                                                #       (not available in ARG_OBJ3)
                                                #     - if :VAR exists in URL, fill it with VAL
                                                #       :VAR takes up to the next '/' or (contrary to $route) the next '.'
                                                #       (unless escaped as \.)
                                                #     - otherwise uses VAR=VAL as GET variable
                                                #     - there are several ways to pass ARG_OBJ:
                                                #        - ARG_OBJ1: for all calls, all methods
                                                #        - ARG_OBJ2: for all calls, specific methods
                                                #        - ARG_OBJ3: for specific calls, specific methods
                                                #  - OBJ2:
                                                #     - stripTrailingSlashes BOOL (déf: true): from URL
                                                #       Can also use $RESOURCEPROVIDER.defaults.stripTrailingSlashes
                                                #  - default ACTION:
                                                #     - get: { method: "GET" }
                                                #     - query: { method: "GET", isArray: true }
                                                #     - save: { method: "POST" }
                                                #     - delete|remove: { method: "DELETE" }
                                                #  - Should be semantically be associated with a REST resource.
                                                #    Idea is to create RSRC_OBJ_SERVICE for each resource

                                  ┌───────────┐
                                  │   LISTS   │
                                  └───────────┘

<any>                                           #Repeat current tag and its children with in each child SCOPE:
  ng-repeat="... in ARR|OBJ[ track by VAL]"     #  - if ARR, ... is "VAR2" being iterated through ARR
                                                #  - if OBJ, ... is "(KEY,VAL)" being iterated through OBJ 
                                                #Each child also gets in its SCOPE:
                                                #  - $index
                                                #  - $first|middle|last BOOL ($middle is any that is not $first|last)
                                                #  - $even|odd BOOL
                                                #If there are nested ng-repeat, can use ng-init="VAR3 = $index" to avoid
                                                #overwriting $index (or $first, etc.)
                                                #If using filter after "...", can alias final filtered result, e.g. 
                                                #"... in ARR | FILTER as VAR4"
                                                #If VAL, it will be evaluated by each child as an ID, then duplicate will not
                                                #be included. VAL can e.g. be VAR2.VAR3
                                                #Uses ANIMEVENT enter, leave and move (reordering)
  ng-class-[odd|even]="EXPR"                    #Like ng-class="EXPR" but on odd|even elements of ng-repeat or its children.
  ui-scroll="VAR in OBJ"                       |#Like ng-repeat="..." but loads elements on scroll. 
                                               |#Also unloads them when scrolling, so never too much DOM even if keep scrolling
                                               |#OBJ:
                                               |#  - get(NUM, NUM2, FUNC(VAL)): gets next item. NUM2 is bufferSize. 
                                               |#    Can control with HTML attribute buffer-size="NUM" (def: 3)
                                               |#  - loading(BOOL): fired when getting new items
                                               |#Scrolling container must have HTML attribute ui-scroll-viewport:
                                               |#  - gets CSS: overflow-y: auto, display: block
                                               |#Can control:
                                               |#  - padding="NUM" (def: 0.1): multiply container outerHeight()
                                               |#MODULE "ui.scroll"

<any>                                          |#Adds class "ui-scrollfix" if scrolling NUM pixels through WINDOW (or parent 
  ui-scrollfix["=+NUM|-NUM"]                   |#element with ui-scrollfix-target)
                                               |#MODULE "ui.scrollfix"

FILTERS ==>                                     #Usually used with ng-options, ng-repeat or ng-class
filter(VAL_ARR, VAL2[, FUNC|BOOL])              #FILTER that returns ARR VAL members that matches VAL2, which can be:
                                                #  - VAL2: VAL == VAL2
                                                #  - OBJ2: OBJ members == OBJ2 members
                                                #    OBJ2 can contain key '$' meaning any member
                                                #  - FUNC(VAL, INDEX)->BOOL
                                                #For VAL2|OBJ2, the meaning of == depends on last argument:
                                                #  - false (déf): contains
                                                #  - true: angular.equals()
                                                #  - FUNC(VAL, VAL2)->BOOL
limitTo(ARR|STR, NUM[, NUM2])                   #FILTER that returns only NUM first elements, or if -NUM, last elements.
                                                #Start at NUM2th element.
orderBy(ARR, VAL[_ARR][, BOOL])                 #FILTER that sorts (in reverse order if false) according to VAL[_ARR]:  
                                                #  - FUNC(VAL)->VAL2, where results will be sorted with <, = and >
                                                #  - VAR_STR: for OBJ, sort according to OBJ.VAR
                                                #If VAL_ARR, use first one, then next one, etc. to sort
unique(ARR[, VAR_STR])                         |#Remove duplicates 
                                               |#If VAR_STR, ARR must be OBJ_ARR: remove duplicates according to OBJ.VAR
                                               |#MODULE "ui.unique"

                                  ┌────────────────┐
                                  │   CONDITIONS   │
                                  └────────────────┘

<any>
  ng-show|hide="BOOL_EXPR"                      #If true, adds "display: none"
                                                #Uses add|removeClass ANIMEVENT (.ng-hide-add|remove)
                                                #To animate, must e.g. use opacity: 0|1 with .ng-hide-* CSS classes
  ui-show|hide="BOOL_EXPR"                     |#Same as ng-class="{ 'ui-show|hide': BOOL_EXPR }"
  ui-toggle="BOOL_EXPR"                        |#Same as ui-show="BOOL_EXPR" ui-hide="! BOOL_EXPR"
                                               |#MODULE "ui.showhide"
  ng-if="BOOL_EXPR"                             #If false, removes element. 
                                                #When true, recreate it using same state as compilation state.
                                                #Uses enter|leave ANIMEVENT
  ng-switch="EXPR"                              #Only shows children that have attribute ng-switch-when="VAL", where
                                                #VAL == EXPR or, if none match, ng-switch-default
                                                #Uses enter|leave ANIMEVENT
<any>                                           
  ng-messages="BOOL_OBJ_EXPR"                   #Must contain children <any ng-message="KEY">
                                                #Will show first children where { KEY: true } in BOOL_OBJ
                                                #Is often used with FORM|NGMODELCONTROLLER.$error
                                                #<any ng-message> uses enter|leave ANIMEVENT
                                                #<any ng-messages> uses .ng-[in]active-add|remove ANIMEVENT (depending on 
                                                #whether a child is being shown)
  ng-messages-multiple                          #With ng-messages, doesn't show only first children, but all matching children.
  ng-messages-include="ID"                      #Uses <script> with ID (type="text/ng-template") with lower priority.
                                                #On ng-message.

                                  ┌─────────────────────┐
                                  │   HTML ATTRIBUTES   │
                                  └─────────────────────┘

<any>
  ng-href="EXPR"
  ng-src="EXPR"
  ng-checked
  ng-required
  ng-readonly                                   #Should use ng-ATTR="{{VAR}}" instead of ATTR="{{VAR}}" for those attributes
  ng-disabled                                   #  - href, src, style
  ng-open                                       #  - <input|etc.>: checked, required, readonly, disabled
  ng-selected                                   #  - <option>: open, selected
  ng-srcset                                     #  - <img>: srcset
  ng-attr-ATTR[="EXPR"]                         #ATTR can contain _ for camelcase, e.g. my_attr targets HTML attribute myAttr

<any>                                           #Like class="{{EXPR}}" but EXPR can be:
  ng-class="EXPR"                               #  - space-separated list STR
                                                #  - STR_ARR, where STR is class or space-separated list of classes
                                                #  - { CLASS: BOOL ... }
                                                #Uses add|removeClass ANIMEVENT

<any>                                           #Similar to HTML inline event handler, but:
  ng-EVENT="EXPR"                               #  ANY_JQ.on( EVENT, function( JQEVENT ) { 
                                                #    SCOPE.$eval(EXPR_STR)
                                                #    SCOPE.$event = JQEVENT //jQuery (if present) or DOM, not AEVENT
                                                #  } );
                                                #EVENT are:
                                                #  - blur, focus, submit, change
                                                #  - key*, mouse*, [dbl]click
                                                #  - copy, paste, cut
                                                #But not:
                                                #  - focusin|out, select, input, contextmenu, scroll
                                                #  - all other events (storage events, drag&drop, etc.)
  ui-event="OBJ_EXPR"                          |#With OBJ.EVENT EXPR_STR: same as ng-EVENT="EXPR", except can use any
                                               |#event, and bound events are an EXPR (so can be dynamic).
                                               |#MODULE "ui.event"
  ui-keypress|down|up="OBJ_EXPR"               |#With OBJ[KEYCODE_STR] EXPR_STR: same as ng-key*="EXPR", but only for a 
                                               |#specific key.
                                               |#KEYCODE_STR:
                                               |#  - is "ctrl|meta|shift|alt-KEY ...": space means "or". dash means "and"
                                               |#  - can be any keyCode NUM, or special keys as STR: "backspace|tab|enter|esc|
                                               |#    space|pageup|pagedown|end|home|left|up|right|down|insert|delete"
                                               |#MODULE "ui.keypress"
  ng-change="EXPR"                              #Fired not on blur, but when $viewValue changes (not $modelValue)

$swipe                                          #SERVICE OBJ. Depends on module ngTouch
SWIPE.bind(AJQ, { EVENT: FUNC ... })            #Bind event handler FUNC({ x: NUM, y: NUM2 }, DOMEVENT) of AJQ to touch EVENT,
                                                #representing a swipe movement (can be done with mouse too):
                                                #  - start: mousedown|touchstart
                                                #  - move: mousemove|touchmove (must first exceed a small threeshold)
                                                #    If direction is mostly vertical, will emit cancel EVENT instead.
                                                #  - end: mouseup|touchend
  ng-swipe-left|right="EXPR"                    #Event handler from module ngTouch
  ng-swipe-disable-mouse                        #To use with ng-swipe-left|right
  ng-click="EXPR"                               #If module ngTouch, is mobile-friendly, and sets CSS class ng-click-active
                                                #while click is held.

ngAria                                          #MODULE that makes some native Angular directives create ARIA attributes:
                                                #  - ng-disabled: aria-disabled
                                                #  - ng-show|hide: aria-hidden
                                                #  - ng-[dbl]click: tabindex
                                                #  - ng-messages: aria-live
                                                #  - ng-model: aria-checked, aria-valuemin|max|now, aria-invalid|required
                                                #  - ng-click, ng-model: role
                                                #  - <div>, <li>: bindKeypress (fires click events on keypress events)
$ariaProvider                                   #PROVIDER
ARIAPROVIDER.config(OBJ)                        #Enables/disables attributes { VAR: BOOL }, e.g. ariaInvalid: false

                                  ┌─────────┐
                                  │   DOM   │
                                  └─────────┘

angular.element(...)                            #If jQuery available, alias to $(...).
                                                #Otherwise, use jQLite, a restricted version.
                                                #All DOM elements are accessed with it in Angular.
                                                #In all cases:
                                                #  - called AJQ in this doc
                                                #  - adds some extra properties
AJQ.on("$destroy", FUNC())                      #Fired by any DOM element removed by a jQuery function, like AJQ.remove().

$window                                         #Like document|window, but using a SERVICE OBJ, which makes it easier to mock,
$document                                       #and as a AJQ. Prefer to use them.

$cookies                                        #SERVICE OBJ, depending on module ngCookies
                                                #Like document.cookie, but as an OBJ. Writing to it only creates cookies
                                                #(i.e. modify document.cookie) after $rootScope.$digest()
                                                #Note: setting document.cookie on file:/// does not work on Chrome.
$cookieStore                                    #Same but using methods.
COOKIES.get[Object](STR)                        #If Object, deserialize and return as OBJ. Otherwise return as STR2.
COOKIES.getAll()                                #Returns OBJ
COOKIES.put[Object](STR, STR2|OBJ[, OBJ2])      #OBJ will be JSON'd|unJSON'd
                                                #OBJ2 has members path|domain|expires|secure
COOKIES.remove(STR[, OBJ2])                     #
$cookiesProvider
COOKIESPROVIDER.defaults.
path|domain|expires|secure                      #

$log                                            #SERVICE OBJ
LOG.log(...)                
LOG.info(...)
LOG.warn(...)                                   #Like console.*
LOG.error(...)                                  #LOG.debug() doesn't do anything if not LOGPROVIDER.debugEnabled([BOOL]) 
LOG.debug(...)                                  #(déf: true)

$interval                                       #Augmented version of setInterval(), which can be mocked
INTERVAL(FUNC(), NUM[, NUM2][, BOOL][, ...])    #Differences with setInterval(FUNC, NUM):
                                                #  - NUM2 (déf: 0, i.e. unlim): number of times before stopping.
                                                #    If >0 and this is the last time, PROMISE will be resolved with number
                                                #    of times called, and INTERVAL will be destroyed.
                                                #  - BOOL: if true (déf), fire FUNC inside $apply()
                                                #  - return a PROMISE. Will be notified at each FUNC() with number of times
                                                #    called.
                                                #  - can bind ... arguments to FUNC()
                                                #  - INTERVAL.cancel(PROMISE): destroy INTERVAL, and reject PROMISE with 
                                                #    "canceled". Returns true if FUNC() has successfully been cancelled.
                                                #    Must be called manually. Does not seem to work.

$timeout                                        #Augmented version of setTimeout(), which can be mocked
TIMEOUT([FUNC(), ]NUM[, BOOL][, ...])           #Same differences as $interval
                                                #PROMISE is not notified, only resolved once

                                  ┌───────────────┐
                                  │   UTILITIES   │
                                  └───────────────┘

angular.copy(VAL)                               #If OBJ|ARR, returns deep copy. Otherwise returns VAL

$q                                              #Like Q, but with only the following members:
                                                #  - Q.defer(), .reject(), .when(), .all()
                                                #  - DEFERRED.resolve|reject|notify(), .promise
                                                #  - PROMISE.then(), .finally(), .catch()
                                                #Also responds to the $apply cycle like other Angular.js components.
                                                #For example, in unit test must do $rootScope.$apply() in afterEach()

$cacheFactory                                   #SERVICE
                                                #Automatically used by $http (but not by def) and $templateCache.
CACHEFACTORY(CACHE_ID_STR[, { capacity: UINT }])#Creates and returns a CACHE (cache database)
                                                #If UINT (déf: unlim), becomes a LRU cache.
CACHEFACTORY.info()                             #Returns { CACHE_ID: { id CACHE_ID_STR, size UINT[, capacity: UINT] } ... } 
                                                #for all CACHE
CACHEFACTORY.get(CACHE_ID_STR)                  #Returns a CACHE, or undefined.

CACHE.info()                                    #
CACHE.put(ID_STR, VAL)                          #Returns VAL
CACHE.get(ID_STR)                               #Returns VAL or undefined
CACHE.remove(ID_STR)                            #
CACHE.removeAll()                               #
CACHE.destroy()                                 #

DSCacheFactory(CACHE_ID_STR[, OBJ])            ##SERVICE, returning DSCACHE. Drop-in replacement for $cacheFactory. 
DSCacheFactory.createCache(CACHE_ID_STR[,OBJ]) ##Must load MODULE angular-data.DSCacheFactory
                                               ##Adds: time expiration, expiration callback, storage choices 
                                               ##(e.g. localStorage or custom), promise handling.
                                               ##Version 3.2.2
                                               ##OBJ can also be specified through:
                                               ##  - DSCacheFactoryProvider.setCacheDefaults(OBJ)
                                               ##  - DSCACHE.setOptions(OBJ) (except storage*)
                                               ##  - DSCACHE.setOBJVAR(VAL) (only cacheFlushInterval, capacity, recycleFreq,
                                               ##    deleteOnExpire, maxAge, onExpire)
                                               ##OBJ:
                                               ##  - capacity NUM (LRU cache)
                                               ##  - disabled BOOL: turns put|get() into noop (does not remove data)
                                               ##  - maxAge NUM (ms): before marking as expired
                                               ##  - deleteOnExpire STR: what to do with items marked as expired. Can be
                                               ##    "none": do nothing (def), "passive": removed when requested and undefined
                                               ##    returned, "aggressive": removed by daemon
                                               ##    Can also use:
                                               ##      - DSCACHE.removeExpired(): Remove and returns all expired items, as OBJ
                                               ##      - DSCACHE.touch([ID_STR]): Reset expiration delay
                                               ##  - recycleFreq NUM (in ms, def: 1000): with "aggressive", how often daemon
                                               ##    is fired
                                               ##  - onExpire(VAR, VAL, FUNC(VAR, VAL)): with "passive". Can also be final
                                               ##    OBJ of DSCACHE.get, as onExpire(VAR, VAL), called after.
                                               ##  - clearFlushInterval NUM (in ms): calls clearAll() periodically
                                               ##  - storageMode STR: how cache is stored. Can be "memory" (def), 
                                               ##    "localStorage" or "sessionStorage".
                                               ##    Actually populates PREFIX.CACHE_ID.data.VAR OBJ: key VAR, value VAL,
                                               ##    created|accessed NUM, expires NUM
                                               ##  - storageImpl OBJ: with storageMode "localStorage|sessionStorage", uses
                                               ##    OBJ.setItem(VAR,VAL), OBJ.getItem(VAR), OBJ.removeItem(VAR) instead
                                               ##  - storagePrefix STR (def: "angular-cache.caches."): prefix used on 
                                               ##    "localStorage|sessionStorage"
                                               ##  - storeOnReject|Resolve BOOL (def: false): when putting a $q PROMISE,
                                               ##    wait until it rejects|resolves to put that value
                                               ##    Can also be final OBJ of DSCACHE.put()
DSCACHEFACTORY.info()                          ##Returns:
                                               ##  - size UINT
                                               ##  - caches.CACHE_ID: DSCACHE.info()
                                               ##  - cacheDefaults OBJ
DSCACHEFACTORY.get(CACHE_ID_STR)               ##Returns a DSCACHE or undefined
DSCACHEFACTORY.keys()                          ##Returns CACHE_ID_STR_ARR
DSCACHEFACTORY.keySet()                        ##Same as { CACHE_ID_STR: CACHE_ID_STR ... }
DSCACHEFACTORY.clearAll()                      ##Remove contents of all DSCACHE
DSCACHEFACTORY.destroyAll()                    ##
DSCACHEFACTORY.enableAll|disableAll()          ##

DSCACHE.info()                                 ##
DSCACHE.put(ID_STR, VAL)                       ##Returns VAL
DSCACHE.get(ID_STR)                            ##Returns VAL or undefined
DSCACHE.remove(ID_STR)                         ##
DSCACHE.removeAll()                            ##
DSCACHE.destroy()                              ##
DSCACHE.enable|disable()                       ##
DSCACHE.keys()                                 ##Returns ID_STR_ARR
DSCACHE.keySet()                               ##Returns { ID_STR: ID_STR ... }


$locale                                         #SERVICE OBJ, representing currently loaded locale, used by core modules.
                                                #To load a different one, include SERVICE definition, available as files
                                                #for each language at
                                                #https://github.com/angular/angular.js/tree/master/src/ngLocale
                                                #Usually loaded in a <script>
LOCALE.id                                       #Like "en-us"
LOCALE.DATETIME_FORMATS                         #OBJ with localized labels of months, date formats, etc.
LOCALE.NUMBER_FORMATS                           #OBJ with currency symbol, separators
LOCALE.pluralCat(UINT)                          #Returns STR according to plural rule in that language.
                                                #STR can be "zero", "one", "two", "few", "many", "other".
                                                #Often only "one" (singular) and "other" (plural)
<ng-pluralize>                                  #Replace content by OBJ_EXPR.CAT where CAT is:
  count="NUM_EXPR"                              #  - LOCALE.pluralCat(NUM - NUM2) (déf. NUM2: 0)
  offset=NUM2                                   #  - if NUM - NUM2 negative, CAT is NUM
  when="OBJ_EXPR"                               #If no offset (most of cases), will use { '0|one|other': STR } as OBJ_EXPR
  when-0|one|other="STR"                        #

                                  ┌─────────────┐
                                  │   TESTING   │
                                  └─────────────┘

E2E TESTING ==>                                 #DOMContentLoaded event is fired after compiling is done, and WD.get(...)
                                                #waits for this event, so there is no problem for e2e testing.

UNIT TESTING ==>                                #Must:
                                                #  - use module() + inject() (see below)
                                                #  - $rootScope.$apply() must be called manually
                                                #  - different components:
                                                #     - service: test directly SERVICE
                                                #     - filter: test $filter(FILTER_STR)
                                                #     - controller: 
                                                #        - in beforeEach():
                                                #           - create SCOPE = $rootScope.new()
                                                #           - fire MYCONTROLLER with:
                                                #               $controller(MYCONTROLLER_STR, { $scope: SCOPE, ... }[, OBJ2])
                                                #             OBJ2 are scope variables coming from bindToController
                                                #           - for nested controllers, must recreate SCOPE hierarchy with 
                                                #             SCOPE2 = SCOPE.new()
                                                #        - in test cases, test SCOPE
                                                #     - directive: 
                                                #        - in beforeEach():
                                                #           - var JQ = $compile(ELEM|HTML_STR)($rootScope), of HTML_STR with 
                                                #             directive (don't attach to document)
                                                #           - $rootScope.$digest()
                                                #           - if testing several related parts, can only compile the root, 
                                                #             then call JQ.find(...) in test cases
                                                #        - in test cases, test JQ
                                                #        - directives with ng-transclude must use not be at root of 
                                                #          ELEM|HTML_STR (can add an empty <div> wrapper)
                                                #     - animation:
                                                #        - compile HTML_STR with animated directive (see directive test above)
                                                #        - to test animation declaration (ANIMEVENT.*()):
                                                #           - simulate events on JQ, then test JQ has [not] class, or has 
                                                #             inserted|removed subelements
                                                #        - to test JavaScript animation consumption:
                                                #           - call ANIMEVENT.*(), then test JavaScript handler has been called 
                                                #             properly
                                                #        - CSS animation consumption cannot be tested, because HTML_STR is not
                                                #          attached to document, so does not have CSS calculated
                                                #     - routing: e2e tests

ngMock                                          #For unit testing.
                                                #Allow using module(MODULE_STR) + inject() in test files:
                                                #  - since unit testing uses empty HTML files, bootstrap MODULE using a
                                                #    non-attached <div ng-app> as $rootElement instead
                                                #  - can then use SERVICE and components with inject()
                                                #  - loads ngMock module, which mock some SERVICE
                                                #  - only works with Jasmine and Mocha
                                                #How:
                                                #  - include angular-mocks.js after the testing framework library, and after 
                                                #    angular.js

module(MODULE_STR...)                           #MODULE_ARR to be loaded by INJECTOR. 
                                                #Must be called before inject(). 
                                                #Should typically be done in beforeEach|testStart()
                                                #Can be called either:
                                                #  - beforeEach|testStart(function() { module(...); });
                                                #  - beforeEach|testStart(module(...)); (simpler)
inject(AFUNC...)                                #Fires INJECTOR.invoke(AFUNC), making it possible to use SERVICE.
                                                #If SERVICE is used in several test cases of the test suite, can assign it to
                                                #a variable in beforeEach|testStart(). Can use _SERVICE_ instead of SERVICE as 
                                                #ARG, in order to assign it to variable called SERVICE.
                                                #INJECTOR is created and destroyed for each test suite.
                                                #Can be called either:
                                                #  - it|test(STR, function() { inject(AFUNC) });
                                                #  - it|test(STR, inject(AFUNC); (simpler)
[t|x]they(STR, ARR|OBJ, FUNC(VAL|OBJ, ...))     #Data-driven testing: like several [x|i]it(STR, FUNC(...))

MOCKS ==>                                       #The following are mocked by ngMock (loaded by module(...)):
                                                #  - $exceptionHandler:
                                                #     - EXCEPTIONHANDLERPROVIDER.mode("rethrow|log"):
                                                #        - "log": push exceptions to $exceptionHandler.errors STR_ARR instead. 
                                                #          Good when test expects exception to be thrown
                                                #        - "rethrow": same as above but also throws it (déf). 
                                                #          Usually good to notify test failed
                                                #  - $log:
                                                #     - adds logs to LOG.log|info|warn|error|debug.logs STR_ARR
                                                #     - LOG.reset()
                                                #     - LOG.assertEmpty()
                                                #  - $interval|timeout:
                                                #     - use fake time, manipulated by INTERVAL|TIMEOUT.flush(NUM)
                                                #     - TIMEOUT.verifyNoPendingTasks()
                                                #  - $httpBackend: fake $http calls (see below)
                                                #  - $scope:
                                                #     - SCOPE.$countChildScopes()->NUM (including isolated, and descendants)
                                                #     - SCOPE.$countWatchers()->NUM (including from child scopes)

HTTPBACKEND.when(METHOD,URL[,BODY[,HEADER_OBJ]])#Parameters:
.respond([STATUS_NUM, ]RESPONSE[, HEADERS_OBJ,  #  - URL|BODY can be STR, REGEXP or FUNC(STR2)->STR
STATUS_STR])                                    #  - OBJ can be FUNC(OBJ2)->OBJ
                                                #  - can also use respond(FUNC(...))->[...], where first ... are same arguments
                                                #    as when(...) and second same as respond(...) but as ARR
                                                #Intercept $http calls matching when(...) and use respond(...) instead:
                                                #  - $http calls are queued and only fired once HTTPBACKEND.flush([NUM])
                                                #    (déf: all pending responses) is executed (fires exception if none pending)
                                                #    Goal of flush() is to allow to simulate async. behavior (doesn't respond 
                                                #    right away) while giving control on when it respond (like sync.).
                                                #  - Should usually be in beforeEach()
                                                #  - can see queued $http calls with HTTP.pendingRequests OBJ_ARR
                                                #Throws error if:
                                                #  - an $http call has been made that does not match any when(...)
                                                #  - there are queued $http calls, then $digest() is called and
                                                #    (must be in afterEach()) HTTPBACKEND.verifyNoOutstandingRequest()
HTTPBACKEND.expect(...)                         #Throws error if no $http call matching a given expect(...) has been done when
                                                #HTTPBACKEND.verifyNoOutstandingExpectation(), must be in afterEach()
                                                #Usually in it() (test cases)
                                                #Parameters:
                                                #  - Same argument as when(...)
                                                #  - FUNC() as argument must return BOOL (true if it matches)
                                                #  - BODY can be OBJ
HTTPBACKEND.expect(ARG...).respond(ARG2...)     #Same as HTTPBACKEND.expect(ARG...); HTTPBACKEND.when(ARG...).respond(ARG2...)
HTTPBACKEND.resetExpectations()                 #Remove all expect(), but not respond()

ngMockE2E                                       #Must include ngMockE2E MODULE in module(...)
                                                #Modify HTTPBACKEND.when(...):
                                                #  - can call HTTPBACKEND.when(...).passThrough() which lets the real request
                                                #    execute
                                                #  - flush() is automatically fired
                                                

                                  ┌───────────────┐
                                  │   NGSTORAGE   │
                                  └───────────────┘

ngStorage                                       #MODULE to use localStorage and sessionStorage 
                                                #(key prefixed with "ngStorage-") as a SERVICE, version 0.3.0
                                                #Stores in JSON
$local|sessionStorage.VAR                       #Gets the value
$local|sessionStorage.VAR = VAL                 #Sets the value
$local|sessionStorage.$default({ VAR: VAL ... })#Sets the value if not set yet
delete $local|sessionStorage.VAR                #Deletes the value
$local|sessionStorage.$reset()                  #Deletes all values

                                  ┌───────────────┐
                                  │   DEBUGGING   │
                                  └───────────────┘

BATARANG ==>                                    #Chrome extension to debug Angular.js:
                                                #  - scopes:
                                                #     - inspect with cursor
                                                #     - shown graphically with borders
                                                #     - browsing tree
                                                #     - click on arrow to highlight element
                                                #     - $scope = scope of highlighted element
                                                #     - AngularJS tab in highlighted Elements
                                                #  - services dependencies graph
                                                #  - show all watched expressions performance
                                                #  - borders to show {{EXPR}}, ng-app (if several)

                                  ┌────────────┐
                                  │   OTHERS   │
                                  └────────────┘

<any>                                          
  ui-jq="FUNC"                                 |#Fires JQ.FUNC([OBJ]). Refired every time EXPR changes.
  ui-options="OBJ"                             |#OBJ can have defaults using ANGULAR.value("uiJqConfig", { FUNC OBJ })
  ui-refresh="EXPR"                            |#MODULE "ui.jq"