docs(location): Add docs for LocationService, LocationConfig

src/common/coreservices.ts

@@ -48,20 +48,108 @@ export interface CoreServices {
 }
 
 export interface LocationServices extends Disposable {
+  /**
+   * Changes the url
+   *
+   * Updates the url, changing it to the value in `newurl`
+   *
+   * #### Example:
+   * ```js
+   * locationServices.setUrl("/some/path?query=value#anchor", true);
+   * ```
+   *
+   * @param newurl The new value for the URL
+   * @param replace When true, replaces the current history entry (instead of appending it) with this new url
+   */
   setUrl(newurl: string, replace?: boolean): void;
+  /**
+   * Gets the path portion of the current url
+   *
+   * If the current URL is `/some/path?query=value#anchor`, this returns `/some/path`
+   *
+   * @return the path portion of the url
+   */
   path(): string;
+  /**
+   * Gets the search portion of the current url as an object
+   *
+   * If the current URL is `/some/path?query=value#anchor`, this returns `{ query: 'value' }`
+   *
+   * @return the search (querystring) portion of the url, as an object
+   */
   search(): { [key: string]: any };
+  /**
+   * Gets the hash portion of the current url
+   *
+   * If the current URL is `/some/path?query=value#anchor`, this returns `anchor`
+   *
+   * @return the hash (anchor) portion of the url
+   */
   hash(): string;
+  /**
+   * Registers a url change handler
+   *
+   * #### Example:
+   * ```js
+   * let deregisterFn = locationServices.onChange((evt) => console.log("url change", evt));
+   * ```
+   *
+   * @param callback a function that will be called when the url is changing
+   * @return a function that de-registers the callback
+   */
   onChange(callback: Function): Function;
 }
 
+/**
+ * This service returns the location configuration
+ *
+ * This service returns information about the location configuration.
+ * This service is primarily used when building URLs (e.g., for `hrefs`)
+ */
 export interface LocationConfig extends Disposable {
+  /**
+   * Gets the port, e.g., `80`
+   *
+   * @return the port number
+   */
   port(): number;
+  /**
+   * Gets the protocol, e.g., `http`
+   *
+   * @return the protocol
+   */
   protocol(): string;
+  /**
+   * Gets the host, e.g., `localhost`
+   *
+   * @return the protocol
+   */
   host(): string;
+  /**
+   * Gets the base Href, e.g., `http://localhost/approot`
+   *
+   * @return the application's base href
+   */
   baseHref(): string;
+  /**
+   * Returns true when running in pushstate mode
+   *
+   * @return true when running in pushstate mode
+   */
   html5Mode(): boolean;
+  /**
+   * Gets the hashPrefix (when not running in pushstate mode)
+   *
+   * If the current url is `http://localhost/app#!/uirouter/path/#anchor`, it returns `!` which is the prefix for the "hashbang" portion.
+   *
+   * @return the hash prefix
+   */
   hashPrefix(): string;
+  /**
+   * Sets the hashPrefix (when not running in pushstate mode)
+   *
+   * @return the new hash prefix
+   */
   hashPrefix(newprefix: string): string;
 }