docs(inherit): Update docs for inherit params to be more consistent.

Closes angular-ui/ui-router#3342

Author: christopherthielen

src/params/interface.ts

@@ -316,10 +316,11 @@ export interface ParamDeclaration {
   raw: boolean;
 
   /**
-   * Enables/disables inheriting of this parameter value
+   * Enables/disables inheriting of this parameter's value
    *
-   * When a transition is run with [[TransitionOptions.inherit]] set to `true`, the current param values are inherited.
-   * Parameters values which have `inherit: false` will not be inherited.
+   * When a transition is run with [[TransitionOptions.inherit]] set to
+   * `true`, the current param values are inherited in the new transition.
+   * However, parameters values which have `inherit: false` set  will *not be inherited*.
    *
    * #### Example state :
    * ```js
@@ -344,6 +345,10 @@ export interface ParamDeclaration {
    *
    * ---
    *
+   * See also [[TransitionOptions.inherit]] and [[ParamTypeDefinition.inherit]]
+   *
+   * ---
+   *
    * Default: `true`
    */
   inherit: boolean;
@@ -577,8 +582,9 @@ export interface ParamTypeDefinition {
   /**
    * Enables/disables inheriting of parameter values (of this type)
    *
-   * When a transition is run with [[TransitionOptions.inherit]] set to `true`, the current param values are inherited.
-   * Param values whose type has `inherit: false` will not be inherited.
+   * When a transition is run with [[TransitionOptions.inherit]] set to
+   * `true`, the current param values are inherited in the new transition.
+   * However, parameters whose type has `inherit: false` set  will *not be inherited*.
    *
    * The internal parameter type of `hash` has `inherit: false`.
    * This is used to disable inheriting of the hash value (`#`) on subsequent transitions.
@@ -592,6 +598,11 @@ export interface ParamTypeDefinition {
    * // The url's hash will be cleared.
    * $state.go('home.nest');
    * ```
+   *
+   * ---
+   *
+   * See also [[TransitionOptions.inherit]] and [[ParamDeclaration.inherit]]
+   *
    */
   inherit?: boolean;
 

src/state/interface.ts

@@ -701,11 +701,32 @@ export interface LazyLoadResult {
   states?: StateDeclaration[];
 }
 
-/** @internalapi */
+/**
+ * An options object for [[StateService.href]]
+ */
 export interface HrefOptions {
+  /**
+   * Defines what state to be "relative from"
+   *
+   * When a relative path is found (e.g `^` or `.bar`), defines which state to be relative from.
+   */
   relative?:  StateOrName;
+
+  /**
+   * If true, and if there is no url associated with the state provided in the
+   *    first parameter, then the constructed href url will be built from the first
+   *    ancestor which has a url.
+   */
   lossy?:     boolean;
+
+  /**
+   * If `true` will inherit parameters from the current parameter values.
+   */
   inherit?:   boolean;
+
+  /**
+   * If true will generate an absolute url, e.g. `http://www.example.com/fullurl`.
+   */
   absolute?:  boolean;
 }
 

src/state/stateObject.ts

@@ -172,10 +172,10 @@ export class StateObject {
   }
 
   /**
-   * Gets the state's `Param`eters
+   * Gets the state's `Param` objects
    *
-   * Gets [[Param]] information that is owned by the state.
-   * If `opts.inherit` is true, it also includes the ancestor states' [[Param]] information.
+   * Gets the list of [[Param]] objects owned by the state.
+   * If `opts.inherit` is true, it also includes the ancestor states' [[Param]] objects.
    * If `opts.matchingKeys` exists, returns only `Param`s whose `id` is a key on the `matchingKeys` object
    *
    * @param opts options
@@ -190,7 +190,7 @@ export class StateObject {
   /**
    * Returns a single [[Param]] that is owned by the state
    *
-   * If `opts.inherit` is true, it also searches the ancestor states` [[Param]] information.
+   * If `opts.inherit` is true, it also searches the ancestor states` [[Param]]s.
    * @param id the name of the [[Param]] to return
    * @param opts options
    */

src/state/stateService.ts

@@ -213,15 +213,15 @@ export class StateService {
   };
 
   /**
-   * Transition to a different state or parameters
+   * Transition to a different state and/or parameters
    *
    * Convenience method for transitioning to a new state.
    *
    * `$state.go` calls `$state.transitionTo` internally but automatically sets options to
-   * `{ location: true, inherit: true, relative: $state.$current, notify: true }`.
-   * This allows you to easily use an absolute or relative to path and specify
-   * only the parameters you'd like to update (while letting unspecified parameters
-   * inherit from the currently active ancestor states).
+   * `{ location: true, inherit: true, relative: router.globals.$current, notify: true }`.
+   * This allows you to use either an absolute or relative `to` argument (because of `relative: router.globals.$current`).
+   * It also allows you to specify * only the parameters you'd like to update, while letting unspecified parameters
+   * inherit from the current parameter values (because of `inherit: true`).
    *
    * #### Example:
    * ```js
@@ -244,12 +244,8 @@ export class StateService {
    *
    * @param params A map of the parameters that will be sent to the state, will populate $stateParams.
    *
-   *    Any parameters that are not specified will be inherited from currently defined parameters (because of `inherit: true`).
-   *    This allows, for example, going to a sibling state that shares parameters specified in a parent state.
-   *
-   *    Parameter inheritance only works between common ancestor states, I.e.
-   *    transitioning to a sibling will get you the parameters for all parents, transitioning to a child
-   *    will get you all current parameters, etc.
+   *    Any parameters that are not specified will be inherited from current parameter values (because of `inherit: true`).
+   *    This allows, for example, going to a sibling state that shares parameters defined by a parent state.
    *
    * @param options Transition options
    *
@@ -496,14 +492,6 @@ export class StateService {
    * @param params An object of parameter values to fill the state's required parameters.
    * @param options Options object. The options are:
    *
-   * - **`lossy`** - {boolean=true} -  If true, and if there is no url associated with the state provided in the
-   *    first parameter, then the constructed href url will be built from the first navigable ancestor (aka
-   *    ancestor with a valid url).
-   * - **`inherit`** - {boolean=true}, If `true` will inherit url parameters from current url.
-   * - **`relative`** - {object=$state.$current}, When transitioning with relative path (e.g '^'),
-   *    defines which state to be relative from.
-   * - **`absolute`** - {boolean=false},  If true will generate an absolute url, e.g. "http://www.example.com/fullurl".
-   *
    * @returns {string} compiled state url
    */
   href(stateOrName: StateOrName, params: RawParams, options?: HrefOptions): string {

src/transition/interface.ts

@@ -37,9 +37,9 @@ export interface TransitionOptions {
 
   /**
    * This option sets whether or not the transition's parameter values should be inherited from
-   * the current state parameters.
+   * the current parameter values.
    *
-   * - If `true`, it will inherit parameters from current state.
+   * - If `true`, it will inherit parameter values from the current parameter values.
    * - If `false`, only the parameters which are provided to `transitionTo` will be used.
    *
    * @default `false`