docs(LocationServices): Clarify docs for url()

Author: christopherthielen

src/common/coreservices.ts

@@ -50,6 +50,29 @@ export interface LocationServices extends Disposable {
   /**
    * Gets the current url string
    *
+   * The URL is normalized using the internal [[path]]/[[search]]/[[hash]] values.
+   *
+   * For example, the URL may be stored in the hash ([[HashLocationServices]]) or
+   * have a base HREF prepended ([[PushStateLocationServices]]).
+   *
+   * The raw URL in the browser might be:
+   *
+   * ```
+   * http://mysite.com/somepath/index.html#/internal/path/123?param1=foo#anchor
+   * ```
+   *
+   * or
+   *
+   * ```
+   * http://mysite.com/basepath/internal/path/123?param1=foo#anchor
+   * ```
+   *
+   * then this method returns:
+   *
+   * ```
+   * /internal/path/123?param1=foo#anchor
+   * ```
+   *
    *
    * #### Example:
    * ```js
@@ -70,7 +93,9 @@ export interface LocationServices extends Disposable {
    * locationServices.url("/some/path?query=value#anchor", true);
    * ```
    *
-   * @param newurl The new value for the URL
+   * @param newurl The new value for the URL.
+   *               This url should reflect only the new internal [[path]], [[search]], and [[hash]] values.
+   *               It should not include the protocol, site, port, or base path of an absolute HREF.
    * @param replace When true, replaces the current history entry (instead of appending it) with this new url
    * @param state The history's state object, i.e., pushState (if the LocationServices implementation supports it)
    * @return the url (after potentially being processed)
@@ -144,7 +169,7 @@ export interface LocationConfig extends Disposable {
    */
   host(): string;
   /**
-   * Gets the base Href, e.g., `http://localhost/approot`
+   * Gets the base Href, e.g., `http://localhost/approot/`
    *
    * @return the application's base href
    */

src/vanilla/baseLocationService.ts

@@ -23,7 +23,31 @@ export abstract class BaseLocationServices implements LocationServices, Disposab
   _location: LocationLike;
   _history: HistoryLike;
 
+  /**
+   * This should return the current internal URL representation.
+   *
+   * The internal URL includes only the portion that UI-Router matches.
+   * It does not include:
+   * - protocol
+   * - server
+   * - port
+   * - base href or hash
+   */
   abstract _get(): string;
+
+  /**
+   * This should set the current URL.
+   *
+   * The `url` param should include only the portion that UI-Router matches on.
+   * It should not include:
+   * - protocol
+   * - server
+   * - port
+   * - base href or hash
+   *
+   * However, after this function completes, the browser URL should reflect the entire (fully qualified)
+   * HREF including those data.
+   */
   abstract _set(state: any, title: string, url: string, replace: boolean);
 
   hash   = () => parseUrl(this._get()).hash;