@angular-wave/angular.ts 0.1.1 → 0.1.2

package/src/core/sce/sce.md

@@ -0,0 +1,300 @@
+/\*\*
+
+- The $sceProvider provider allows developers to configure the {@link ng.$sce $sce} service.
+- - enable/disable Strict Contextual Escaping (SCE) in a module
+- - override the default implementation with a custom delegate
+-
+- Read more about {@link ng.$sce Strict Contextual Escaping (SCE)}.
+  \*/
+
+/\*\*
+
+-
+- `$sce` is a service that provides Strict Contextual Escaping services to AngularJS.
+-
+- ## Strict Contextual Escaping
+-
+- Strict Contextual Escaping (SCE) is a mode in which AngularJS constrains bindings to only render
+- trusted values. Its goal is to assist in writing code in a way that (a) is secure by default, and
+- (b) makes auditing for security vulnerabilities such as XSS, clickjacking, etc. a lot easier.
+-
+- ### Overview
+-
+- To systematically block XSS security bugs, AngularJS treats all values as untrusted by default in
+- HTML or sensitive URL bindings. When binding untrusted values, AngularJS will automatically
+- run security checks on them (sanitizations, trusted URL resource, depending on context), or throw
+- when it cannot guarantee the security of the result. That behavior depends strongly on contexts:
+- HTML can be sanitized, but template URLs cannot, for instance.
+-
+- To illustrate this, consider the `ng-bind-html` directive. It renders its value directly as HTML:
+- we call that the _context_. When given an untrusted input, AngularJS will attempt to sanitize it
+- before rendering if a sanitizer is available, and throw otherwise. To bypass sanitization and
+- render the input as-is, you will need to mark it as trusted for that context before attempting
+- to bind it.
+-
+- As of version 1.2, AngularJS ships with SCE enabled by default.
+-
+- ### In practice
+-
+- Here's an example of a binding in a privileged context:
+-
+- ```
+
+  ```
+
+- <input ng-model="userHtml" aria-label="User input">
+- <div ng-bind-html="userHtml"></div>
+- ```
+
+  ```
+
+-
+- Notice that `ng-bind-html` is bound to `userHtml` controlled by the user. With SCE
+- disabled, this application allows the user to render arbitrary HTML into the DIV, which would
+- be an XSS security bug. In a more realistic example, one may be rendering user comments, blog
+- articles, etc. via bindings. (HTML is just one example of a context where rendering user
+- controlled input creates security vulnerabilities.)
+-
+- For the case of HTML, you might use a library, either on the client side, or on the server side,
+- to sanitize unsafe HTML before binding to the value and rendering it in the document.
+-
+- How would you ensure that every place that used these types of bindings was bound to a value that
+- was sanitized by your library (or returned as safe for rendering by your server?) How can you
+- ensure that you didn't accidentally delete the line that sanitized the value, or renamed some
+- properties/fields and forgot to update the binding to the sanitized value?
+-
+- To be secure by default, AngularJS makes sure bindings go through that sanitization, or
+- any similar validation process, unless there's a good reason to trust the given value in this
+- context. That trust is formalized with a function call. This means that as a developer, you
+- can assume all untrusted bindings are safe. Then, to audit your code for binding security issues,
+- you just need to ensure the values you mark as trusted indeed are safe - because they were
+- received from your server, sanitized by your library, etc. You can organize your codebase to
+- help with this - perhaps allowing only the files in a specific directory to do this.
+- Ensuring that the internal API exposed by that code doesn't markup arbitrary values as safe then
+- becomes a more manageable task.
+-
+- In the case of AngularJS' SCE service, one uses {@link ng.$sce#trustAs $sce.trustAs}
+- (and shorthand methods such as {@link ng.$sce#trustAsHtml $sce.trustAsHtml}, etc.) to
+- build the trusted versions of your values.
+-
+- ### How does it work?
+-
+- In privileged contexts, directives and code will bind to the result of {@link ng.$sce#getTrusted
+- $sce.getTrusted(context, value)} rather than to the value directly. Think of this function as
+- a way to enforce the required security context in your data sink. Directives use {@link
+- ng.$sce#parseAs $sce.parseAs} rather than `$parse` to watch attribute bindings, which performs
+- the {@link ng.$sce#getTrusted $sce.getTrusted} behind the scenes on non-constant literals. Also,
+- when binding without directives, AngularJS will understand the context of your bindings
+- automatically.
+-
+- As an example, {@link ng.directive:ngBindHtml ngBindHtml} uses {@link
+- ng.$sce#parseAsHtml $sce.parseAsHtml(binding expression)}. Here's the actual code (slightly
+- simplified):
+-
+- ```
+
+  ```
+
+- let ngBindHtmlDirective = ['$sce', function($sce) {
+- return function(scope, element, attr) {
+-     scope.$watch($sce.parseAsHtml(attr.ngBindHtml), function(value) {
+-       element.html(value || '');
+-     });
+- };
+- }];
+- ```
+
+  ```
+
+-
+- ### Impact on loading templates
+-
+- This applies both to the {@link ng.directive:ngInclude `ng-include`} directive as well as
+- `templateUrl`'s specified by {@link guide/directive directives}.
+-
+- By default, AngularJS only loads templates from the same domain and protocol as the application
+- document. This is done by calling {@link ng.$sce#getTrustedResourceUrl
+- $sce.getTrustedResourceUrl} on the template URL. To load templates from other domains and/or
+- protocols, you may either add them to the {@link ng.$sceDelegateProvider#trustedResourceUrlList
+- trustedResourceUrlList} or {@link ng.$sce#trustAsResourceUrl wrap them} into trusted values.
+-
+- _Please note_:
+- The browser's
+- [Same Origin Policy](https://code.google.com/p/browsersec/wiki/Part2#Same-origin_policy_for_XMLHttpRequest)
+- and [Cross-Origin Resource Sharing (CORS)](http://www.w3.org/TR/cors/)
+- policy apply in addition to this and may further restrict whether the template is successfully
+- loaded. This means that without the right CORS policy, loading templates from a different domain
+- won't work on all browsers. Also, loading templates from `file://` URL does not work on some
+- browsers.
+-
+- ### This feels like too much overhead
+-
+- It's important to remember that SCE only applies to interpolation expressions.
+-
+- If your expressions are constant literals, they're automatically trusted and you don't need to
+- call `$sce.trustAs` on them (e.g.
+- `<div ng-bind-html="'<b>implicitly trusted</b>'"></div>`) just works (remember to include the
+- `ngSanitize` module). The `$sceDelegate` will also use the `$sanitize` service if it is available
+- when binding untrusted values to `$sce.HTML` context.
+- AngularJS provides an implementation in `angular-sanitize.js`, and if you
+- wish to use it, you will also need to depend on the {@link ngSanitize `ngSanitize`} module in
+- your application.
+-
+- The included {@link ng.$sceDelegate $sceDelegate} comes with sane defaults to allow you to load
+- templates in `ng-include` from your application's domain without having to even know about SCE.
+- It blocks loading templates from other domains or loading templates over http from an https
+- served document. You can change these by setting your own custom {@link
+- ng.$sceDelegateProvider#trustedResourceUrlList trusted resource URL list} and {@link
+- ng.$sceDelegateProvider#bannedResourceUrlList banned resource URL list} for matching such URLs.
+-
+- This significantly reduces the overhead. It is far easier to pay the small overhead and have an
+- application that's secure and can be audited to verify that with much more ease than bolting
+- security onto an application later.
+-
+- <a name="contexts"></a>
+- ### What trusted context types are supported?
+-
+- | Context | Notes |
+- |---------------------|----------------|
+- | `$sce.HTML` | For HTML that's safe to source into the application. The {@link ng.directive:ngBindHtml ngBindHtml} directive uses this context for bindings. If an unsafe value is encountered and the {@link ngSanitize $sanitize} module is present this will sanitize the value instead of throwing an error. |
+- | `$sce.CSS` | For CSS that's safe to source into the application. Currently unused. Feel free to use it in your own directives. |
+- | `$sce.MEDIA_URL` | For URLs that are safe to render as media. Is automatically converted from string by sanitizing when needed. |
+- | `$sce.URL` | For URLs that are safe to follow as links. Is automatically converted from string by sanitizing when needed. Note that `$sce.URL` makes a stronger statement about the URL than `$sce.MEDIA_URL` does and therefore contexts requiring values trusted for `$sce.URL` can be used anywhere that values trusted for `$sce.MEDIA_URL` are required.|
+- | `$sce.RESOURCE_URL` | For URLs that are not only safe to follow as links, but whose contents are also safe to include in your application. Examples include `ng-include`, `src` / `ngSrc` bindings for tags other than `IMG` (e.g. `IFRAME`, `OBJECT`, etc.) <br><br>Note that `$sce.RESOURCE_URL` makes a stronger statement about the URL than `$sce.URL` or `$sce.MEDIA_URL` do and therefore contexts requiring values trusted for `$sce.RESOURCE_URL` can be used anywhere that values trusted for `$sce.URL` or `$sce.MEDIA_URL` are required. <br><br> The {@link $sceDelegateProvider#trustedResourceUrlList $sceDelegateProvider#trustedResourceUrlList()} and {@link $sceDelegateProvider#bannedResourceUrlList $sceDelegateProvider#bannedResourceUrlList()} can be used to restrict trusted origins for `RESOURCE_URL` |
+- | `$sce.JS` | For JavaScript that is safe to execute in your application's context. Currently unused. Feel free to use it in your own directives. |
+-
+-
+- <div class="alert alert-warning">
+- Be aware that, before AngularJS 1.7.0, `a[href]` and `img[src]` used to sanitize their
+- interpolated values directly rather than rely upon {@link ng.$sce#getTrusted `$sce.getTrusted`}.
+-
+- **As of 1.7.0, this is no longer the case.**
+-
+- Now such interpolations are marked as requiring `$sce.URL` (for `a[href]`) or `$sce.MEDIA_URL`
+- (for `img[src]`), so that the sanitization happens (via `$sce.getTrusted...`) when the `$interpolate`
+- service evaluates the expressions.
+- </div>
+-
+- There are no CSS or JS context bindings in AngularJS currently, so their corresponding `$sce.trustAs`
+- functions aren't useful yet. This might evolve.
+-
+- ### Format of items in {@link ng.$sceDelegateProvider#trustedResourceUrlList trustedResourceUrlList}/{@link ng.$sceDelegateProvider#bannedResourceUrlList bannedResourceUrlList} <a name="resourceUrlPatternItem"></a>
+-
+- Each element in these arrays must be one of the following:
+-
+- - **'self'**
+- - The special **string**, `'self'`, can be used to match against all URLs of the \*\*same
+-      domain** as the application document using the **same protocol**.
+- - **String** (except the special value `'self'`)
+- - The string is matched against the full _normalized / absolute URL_ of the resource
+-      being tested (substring matches are not good enough.)
+- - There are exactly **two wildcard sequences** - `*` and `**`. All other characters
+-      match themselves.
+- - `*`: matches zero or more occurrences of any character other than one of the following 6
+-      characters: '`:`', '`/`', '`.`', '`?`', '`&`' and '`;`'.  It's a useful wildcard for use
+-      for matching resource URL lists.
+- - `**`: matches zero or more occurrences of _any_ character. As such, it's not
+-      appropriate for use in a scheme, domain, etc. as it would match too much.  (e.g.
+-      http://**.example.com/ would match http://evil.com/?ignore=.example.com/ and that might
+-      not have been the intention.)  Its usage at the very end of the path is ok.  (e.g.
+-      http://foo.example.com/templates/**).
+- - **RegExp** (_see caveat below_)
+- - _Caveat_: While regular expressions are powerful and offer great flexibility, their syntax
+-      (and all the inevitable escaping) makes them *harder to maintain*.  It's easy to
+-      accidentally introduce a bug when one updates a complex expression (imho, all regexes should
+-      have good test coverage).  For instance, the use of `.` in the regex is correct only in a
+-      small number of cases.  A `.` character in the regex used when matching the scheme or a
+-      subdomain could be matched against a `:` or literal `.` that was likely not intended.   It
+-      is highly recommended to use the string patterns and only fall back to regular expressions
+-      as a last resort.
+- - The regular expression must be an instance of RegExp (i.e. not a string.) It is
+-      matched against the **entire** *normalized / absolute URL* of the resource being tested
+-      (even when the RegExp did not have the `^` and `$` codes.)  In addition, any flags
+-      present on the RegExp (such as multiline, global, ignoreCase) are ignored.
+- - If you are generating your JavaScript from some other templating engine (not
+-      recommended, e.g. in issue [#4006](https://github.com/angular/angular.js/issues/4006)),
+-      remember to escape your regular expression (and be aware that you might need more than
+-      one level of escaping depending on your templating engine and the way you interpolated
+-      the value.)  Do make use of your platform's escaping mechanism as it might be good
+-      enough before coding your own.  E.g. Ruby has
+-      [Regexp.escape(str)](http://www.ruby-doc.org/core-2.0.0/Regexp.html#method-c-escape)
+-      and Python has [re.escape](http://docs.python.org/library/re.html#re.escape).
+-      Javascript lacks a similar built in function for escaping.  Take a look at Google
+-      Closure library's [goog.string.regExpEscape(s)](
+-      http://docs.closure-library.googlecode.com/git/closure_goog_string_string.js.source.html#line962).
+-
+- Refer {@link ng.$sceDelegateProvider $sceDelegateProvider} for an example.
+-
+-
+- ## Can I disable SCE completely?
+-
+- Yes, you can. However, this is strongly discouraged. SCE gives you a lot of security benefits
+- for little coding overhead. It will be much harder to take an SCE disabled application and
+- either secure it on your own or enable SCE at a later stage. It might make sense to disable SCE
+- for cases where you have a lot of existing code that was written before SCE was introduced and
+- you're migrating them a module at a time. Also do note that this is an app-wide setting, so if
+- you are writing a library, you will cause security bugs applications using it.
+-
+- That said, here's how you can completely disable SCE:
+-
+- ```
+
+  ```
+
+- angular.module('myAppWithSceDisabledmyApp', []).config(function($sceProvider) {
+- // Completely disable SCE. For demonstration purposes only!
+- // Do not use in new projects or libraries.
+- $sceProvider.enabled(false);
+- });
+- ```
+
+  ```
+
+- \*/
+
+/\* Design notes on the default implementation for SCE.
+
+-
+- The API contract for the SCE delegate
+- ***
+- The SCE delegate object must provide the following 3 methods:
+-
+- - trustAs(contextEnum, value)
+-     This method is used to tell the SCE service that the provided value is OK to use in the
+-     contexts specified by contextEnum.  It must return an object that will be accepted by
+-     getTrusted() for a compatible contextEnum and return this value.
+-
+- - valueOf(value)
+-     For values that were not produced by trustAs(), return them as is.  For values that were
+-     produced by trustAs(), return the corresponding input value to trustAs.  Basically, if
+-     trustAs is wrapping the given values into some type, this operation unwraps it when given
+-     such a value.
+-
+- - getTrusted(contextEnum, value)
+-     This function should return the value that is safe to use in the context specified by
+-     contextEnum or throw and exception otherwise.
+-
+- NOTE: This contract deliberately does NOT state that values returned by trustAs() must be
+- opaque or wrapped in some holder object. That happens to be an implementation detail. For
+- instance, an implementation could maintain a registry of all trusted objects by context. In
+- such a case, trustAs() would return the same object that was passed in. getTrusted() would
+- return the same object passed in if it was found in the registry under a compatible context or
+- throw an exception otherwise. An implementation might only wrap values some of the time based
+- on some criteria. getTrusted() might return a value and not throw an exception for special
+- constants or objects even if not wrapped. All such implementations fulfill this contract.
+-
+-
+- A note on the inheritance model for SCE contexts
+- ***
+- I've used inheritance and made RESOURCE_URL wrapped types a subtype of URL wrapped types. This
+- is purely an implementation details.
+-
+- The contract is simply this:
+-
+-     getTrusted($sce.RESOURCE_URL, value) succeeding implies that getTrusted($sce.URL, value)
+-     will also succeed.
+-
+- Inheritance happens to capture this in a natural way. In some future, we may not use
+- inheritance anymore. That is OK because no code outside of sce.js and sceSpecs.js would need to
+- be aware of this detail.
+  \*/

package/src/core/scope/scope.js

@@ -287,11 +287,6 @@ export class Scope {
   }
 
   /**
- * @ngdoc method
- * @name $rootScope.Scope#$watch
- * @kind function
- *
- * @description
  * Registers a `listener` callback to be executed whenever the `watchExpression` changes.
  *
  * - The `watchExpression` is called on every call to {@link ng.$rootScope.Scope#$digest
@@ -437,11 +432,6 @@ export class Scope {
   }
 
   /**
-   * @ngdoc method
-   * @name $rootScope.Scope#$watchGroup
-   * @kind function
-   *
-   * @description
    * A variant of {@link ng.$rootScope.Scope#$watch $watch()} where it watches an array of `watchExpressions`.
    * If any one expression in the collection changes the `listener` is executed.
    *
@@ -525,11 +515,6 @@ export class Scope {
   }
 
   /**
-   * @ngdoc method
-   * @name $rootScope.Scope#$watchCollection
-   * @kind function
-   *
-   * @description
    * Shallow watches the properties of an object and fires whenever any of the properties change
    * (for arrays, this implies watching the array items; for object maps, this implies watching
    * the properties). If a change is detected, the `listener` callback is fired.
@@ -701,11 +686,6 @@ export class Scope {
   }
 
   /**
- * @ngdoc method
- * @name $rootScope.Scope#$digest
- * @kind function
- *
- * @description
  * Processes all of the {@link ng.$rootScope.Scope#$watch watchers} of the current scope and
  * its children. Because a {@link ng.$rootScope.Scope#$watch watcher}'s listener can change
  * the model, the `$digest()` keeps calling the {@link ng.$rootScope.Scope#$watch watchers}
@@ -920,11 +900,6 @@ export class Scope {
   }
 
   /**
-   * @ngdoc method
-   * @name $rootScope.Scope#$suspend
-   * @kind function
-   *
-   * @description
    * Suspend watchers of this scope subtree so that they will not be invoked during digest.
    *
    * This can be used to optimize your application when you know that running those watchers
@@ -967,11 +942,7 @@ export class Scope {
   }
 
   /**
-   * @ngdoc method
-   * @name $rootScope.Scope#$isSuspended
-   * @kind function
-   *
-   * @description
+
    * Call this method to determine if this scope has been explicitly suspended. It will not
    * tell you whether an ancestor has been suspended.
    * To determine if this scope will be excluded from a digest triggered at the $rootScope,
@@ -996,11 +967,6 @@ export class Scope {
   }
 
   /**
-   * @ngdoc method
-   * @name $rootScope.Scope#$resume
-   * @kind function
-   *
-   * @description
    * Resume watchers of this scope subtree in case it was suspended.
    *
    * See {@link $rootScope.Scope#$suspend} for information about the dangers of using this approach.
@@ -1010,11 +976,6 @@ export class Scope {
   }
 
   /**
-   * @ngdoc event
-   * @name $rootScope.Scope#$destroy
-   * @eventType broadcast on scope being destroyed
-   *
-   * @description
    * Broadcasted when a scope and its children are being destroyed.
    *
    * Note that, in AngularTS, there is also a `$destroy` jQuery event, which can be used to
@@ -1022,11 +983,6 @@ export class Scope {
    */
 
   /**
-   * @ngdoc method
-   * @name $rootScope.Scope#$destroy
-   * @kind function
-   *
-   * @description
    * Removes the current scope (and all of its children) from the parent scope. Removal implies
    * that calls to {@link ng.$rootScope.Scope#$digest $digest()} will no longer
    * propagate to the current scope and its children. Removal also implies that the current
@@ -1096,11 +1052,6 @@ export class Scope {
   }
 
   /**
- * @ngdoc method
- * @name $rootScope.Scope#$eval
- * @kind function
- *
- * @description
  * Executes the `expression` on the current scope and returns the result. Any exceptions in
  * the expression are propagated (uncaught). This is useful when evaluating AngularTS
  * expressions.
@@ -1128,11 +1079,6 @@ export class Scope {
   }
 
   /**
-   * @ngdoc method
-   * @name $rootScope.Scope#$evalAsync
-   * @kind function
-   *
-   * @description
    * Executes the expression on the current scope at a later point in time.
    *
    * The `$evalAsync` makes no guarantees as to when the `expression` will be executed, only
@@ -1187,11 +1133,6 @@ export class Scope {
   }
 
   /**
- * @ngdoc method
- * @name $rootScope.Scope#$apply
- * @kind function
- *
- * @description
  * `$apply()` is used to execute an expression in AngularTS from outside of the AngularTS
  * framework. (For example from browser DOM events, setTimeout, XHR or third party libraries).
  * Because we are calling into the AngularTS framework we need to perform proper scope life
@@ -1262,11 +1203,6 @@ export class Scope {
   }
 
   /**
-   * @ngdoc method
-   * @name $rootScope.Scope#$applyAsync
-   * @kind function
-   *
-   * @description
    * Schedule the invocation of $apply to occur at a later time. The actual time difference
    * varies across browsers, but is typically around ~10 milliseconds.
    *
@@ -1368,11 +1304,6 @@ export class Scope {
   }
 
   /**
-   * @ngdoc method
-   * @name $rootScope.Scope#$emit
-   * @kind function
-   *
-   * @description
    * Dispatches an event `name` upwards through the scope hierarchy notifying the
    * registered {@link ng.$rootScope.Scope#$on} listeners.
    *
@@ -1442,11 +1373,6 @@ export class Scope {
   }
 
   /**
-   * @ngdoc method
-   * @name $rootScope.Scope#$broadcast
-   * @kind function
-   *
-   * @description
    * Dispatches an event `name` downwards to all child scopes (and their children) notifying the
    * registered {@link ng.$rootScope.Scope#$on} listeners.
    *

package/src/core/url-utils/url-utils.js

@@ -5,59 +5,12 @@ import { isString } from "../../shared/utils";
  * @typedef {"http"|"https"} HttpProtocol
  */
 
-// service.
 const urlParsingNode = window.document.createElement("a");
 const originUrl = urlResolve(window.location.href);
 let baseUrlParsingNode;
 
 urlParsingNode.href = "http://[::1]";
 
-/**
- *
- * Implementation Notes for non-IE browsers
- * ----------------------------------------
- * Assigning a URL to the href property of an anchor DOM node, even one attached to the DOM,
- * results both in the normalizing and parsing of the URL.  Normalizing means that a relative
- * URL will be resolved into an absolute URL in the context of the application document.
- * Parsing means that the anchor node's host, hostname, protocol, port, pathname and related
- * properties are all populated to reflect the normalized URL.  This approach has wide
- * compatibility - Safari 1+, Mozilla 1+ etc.  See
- * http://www.aptana.com/reference/html/api/HTMLAnchorElement.html
- *
- * Implementation Notes for IE
- * ---------------------------
- * IE <= 10 normalizes the URL when assigned to the anchor node similar to the other
- * browsers.  However, the parsed components will not be set if the URL assigned did not specify
- * them.  (e.g. if you assign a.href = "foo", then a.protocol, a.host, etc. will be empty.)  We
- * work around that by performing the parsing in a 2nd step by taking a previously normalized
- * URL (e.g. by assigning to a.href) and assigning it a.href again.  This correctly populates the
- * properties such as protocol, hostname, port, etc.
- *
- * References:
- *   http://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement
- *   http://www.aptana.com/reference/html/api/HTMLAnchorElement.html
- *   http://url.spec.whatwg.org/#urlutils
- *   https://github.com/angular/angular.js/pull/2902
- *   http://james.padolsey.com/javascript/parsing-urls-with-the-dom/
- *
- * @kind function
- * @param {string|object} url The URL to be parsed. If `url` is not a string, it will be returned
- *     unchanged.
- * @description Normalizes and parses a URL.
- * @returns {object} Returns the normalized URL as a dictionary.
- *
- *   | member name   | Description                                                            |
- *   |---------------|------------------------------------------------------------------------|
- *   | href          | A normalized version of the provided URL if it was not an absolute URL |
- *   | protocol      | The protocol without the trailing colon                                |
- *   | host          | The host and port (if the port is non-default) of the normalizedUrl    |
- *   | search        | The search params, minus the question mark                             |
- *   | hash          | The hash string, minus the hash symbol                                 |
- *   | hostname      | The hostname                                                           |
- *   | port          | The port, without ":"                                                  |
- *   | pathname      | The pathname, beginning with "/"                                       |
- *
- */
 export function urlResolve(url) {
   if (!isString(url)) return url;
 

package/src/core/url-utils/url-utils.md

@@ -0,0 +1,46 @@
+/\*\*
+
+-
+- Implementation Notes for non-IE browsers
+- ***
+- Assigning a URL to the href property of an anchor DOM node, even one attached to the DOM,
+- results both in the normalizing and parsing of the URL. Normalizing means that a relative
+- URL will be resolved into an absolute URL in the context of the application document.
+- Parsing means that the anchor node's host, hostname, protocol, port, pathname and related
+- properties are all populated to reflect the normalized URL. This approach has wide
+- compatibility - Safari 1+, Mozilla 1+ etc. See
+- http://www.aptana.com/reference/html/api/HTMLAnchorElement.html
+-
+- Implementation Notes for IE
+- ***
+- IE <= 10 normalizes the URL when assigned to the anchor node similar to the other
+- browsers. However, the parsed components will not be set if the URL assigned did not specify
+- them. (e.g. if you assign a.href = "foo", then a.protocol, a.host, etc. will be empty.) We
+- work around that by performing the parsing in a 2nd step by taking a previously normalized
+- URL (e.g. by assigning to a.href) and assigning it a.href again. This correctly populates the
+- properties such as protocol, hostname, port, etc.
+-
+- References:
+- http://developer.mozilla.org/en-US/docs/Web/API/HTMLAnchorElement
+- http://www.aptana.com/reference/html/api/HTMLAnchorElement.html
+- http://url.spec.whatwg.org/#urlutils
+- https://github.com/angular/angular.js/pull/2902
+- http://james.padolsey.com/javascript/parsing-urls-with-the-dom/
+-
+- @kind function
+- @param {string|object} url The URL to be parsed. If `url` is not a string, it will be returned
+-     unchanged.
+- @description Normalizes and parses a URL.
+- @returns {object} Returns the normalized URL as a dictionary.
+-
+- | member name | Description |
+- |---------------|------------------------------------------------------------------------|
+- | href | A normalized version of the provided URL if it was not an absolute URL |
+- | protocol | The protocol without the trailing colon |
+- | host | The host and port (if the port is non-default) of the normalizedUrl |
+- | search | The search params, minus the question mark |
+- | hash | The hash string, minus the hash symbol |
+- | hostname | The hostname |
+- | port | The port, without ":" |
+- | pathname | The pathname, beginning with "/" |
+- \*/

package/src/directive/aria/aria.js

@@ -20,13 +20,8 @@ const isNodeOneOf = function (elem, nodeTypeArray) {
     return true;
   }
 };
+
 /**
- * @ngdoc provider
- * @name $ariaProvider
- *
- *
- * @description
- *
  * Used for configuring the ARIA attributes injected and managed by ngAria.
  *
  * ```js

package/src/directive/class/class.js

@@ -166,12 +166,6 @@ function classDirective(name, selector) {
 }
 
 /**
- * @ngdoc directive
- * @name ngClass
- * @restrict AC
- * @element ANY
- *
- * @description
  * The `ngClass` directive allows you to dynamically set CSS classes on an HTML element by databinding
  * an expression that represents all classes to be added.
  *
@@ -223,11 +217,6 @@ function classDirective(name, selector) {
 export const ngClassDirective = classDirective("", true);
 
 /**
- * @ngdoc directive
- * @name ngClassOdd
- * @restrict AC
- *
- * @description
  * The `ngClassOdd` and `ngClassEven` directives work exactly as
  * {@link ng.directive:ngClass ngClass}, except they work in
  * conjunction with `ngRepeat` and take effect only on odd (even) rows.
@@ -250,11 +239,6 @@ export const ngClassDirective = classDirective("", true);
 export const ngClassOddDirective = classDirective("Odd", 0);
 
 /**
- * @ngdoc directive
- * @name ngClassEven
- * @restrict AC
- *
- * @description
  * The `ngClassOdd` and `ngClassEven` directives work exactly as
  * {@link ng.directive:ngClass ngClass}, except they work in
  * conjunction with `ngRepeat` and take effect only on odd (even) rows.