chore(docs): use DOCS.md for documentation idx. Improve docs:

- Use consistent deprecation warnings.
- Use consistent #### Example: markup
- Fix broken  [[foo]] links

Author: christopherthielen

DOCS.md

@@ -0,0 +1,48 @@
+# [UI Router for Angular 1](https://ui-router.github.io/ng1/docs/latest)
+
+#### The de-facto solution to flexible routing in angular 1
+
+<div style="display: flex;">
+
+<iframe style="display: inline-block;" src="https://ghbtns.com/github-btn.html?user=angular-ui&repo=ui-router&type=fork&count=true&size=medium" frameborder="0" scrolling="0" width="110px" height="20px"></iframe>
+<iframe style="display: inline-block;" src="https://ghbtns.com/github-btn.html?user=angular-ui&repo=ui-router&type=star&count=true&size=medium" frameborder="0" scrolling="0" width="110px" height="20px"></iframe>
+[![Build Status](https://travis-ci.org/angular-ui/ui-router.svg?branch=master)](https://travis-ci.org/angular-ui/ui-router)
+
+</div>
+
+
+Angular UI-Router is a client-side [Single Page Application](https://en.wikipedia.org/wiki/Single-page_application) 
+routing framework for [AngularJS](http://angularjs.org).  
+
+**[View on Github](http://github.com/angular-ui/ui-router) |**
+**[Tutorials](https://ui-router.github.io/ng1/tutorials/)** |
+**[Guides](https://ui-router.github.io/guide) |**
+**[Sample App](http://ui-router.github.io/resources/sampleapp/) |**
+**[Wiki](https://github.com/angular-ui/ui-router/wiki) |**
+**[FAQ](https://github.com/angular-ui/ui-router/wiki/Frequently-Asked-Questions)**
+  
+#### API Documentation Organization
+
+The documentation is arranged according to API concern, such as `url`, `resolve`, and `core`.
+For a list of services and objects that can be injectable, see the [`injectables` section](./injectables.html).
+
+By default, only the public UI-Router API is shown.
+To view both public API and the internal APIs, check the "Internal UI-Router API" checkbox.
+  
+#### Typescript
+
+UI-Router is written in Typescript.
+The API documentation is generated using [TypeDoc](https://github.com/TypeStrong/typedoc).
+The documentation reflects the Typescript classes, interfaces, and parameter types information embedded in the source code.
+
+#### Contributing
+
+Angular UI-Router depends on the framework agnostic `ui-router-core`.
+To contribute to the documentation, please submit a PR to either 
+[angular-ui-router](http://github.com/angular-ui/ui-router)
+or
+[ui-router-core](http://github.com/ui-router/core).
+To find where a specific piece of documentation is written, follow the links that say:
+ > _Defined in ui-router/somedir/somefile.ts_
+
+

scripts/docs.js

@@ -6,7 +6,7 @@ let replaceInFiles = require('replace-in-file');
 
 let typedocCmd = [
   "./node_modules/typedoc/bin/typedoc --tsconfig tsconfig.typedoc.json ",
-  " --readme README.md ",
+  " --readme DOCS.md ",
   " --name 'angular-ui-router' ",
   " --theme node_modules/ui-router-typedoc-themes/bin/default ",
   " --out _doc ",

src/directives/stateDirectives.ts

@@ -1,7 +1,8 @@
 /**
- * These are the UI-Router angular 1 directives.
+ * # Angular 1 Directives
  *
- * These directives are used in templates to create viewports and navigate to states
+ * These are the directives included in UI-Router for Angular 1.
+ * These directives are used in templates to create viewports and link/navigate to states.
  *
  * @ng1api
  * @preferred
@@ -288,6 +289,7 @@ uiSref = ['$uiRouter', '$timeout',
  * <li ng-repeat="link in navlinks">
  *   <a ui-sref="link.state">{{ link.displayName }}</a>
  * </li>
+ * ```
  *
  * ### Relative Links
  * If the expression evaluates to a relative path, it is processed like [[uiSref]].
@@ -430,7 +432,7 @@ uiState = ['$uiRouter', '$timeout',
  * ### Examples
  *
  * Given the following template:
- * @example
+ * #### Example:
  * ```html
  * <ul>
  *   <li ui-sref-active="active" class="item">

src/directives/viewDirective.ts

@@ -46,10 +46,9 @@ export type UIViewAnimData = {
  *
  * - `onload`: Expression to evaluate whenever the view updates.
  *
+ * #### Example:
  * A view can be unnamed or named.
- * @example
  * ```html
- *
  * <!-- Unnamed -->
  * <div ui-view></div>
  *
@@ -62,18 +61,18 @@ export type UIViewAnimData = {
  *
  * You can only have one unnamed view within any template (or root html). If you are only using a
  * single view and it is unnamed then you can populate it like so:
- * ```
  *
+ * ```html
  * <div ui-view></div>
  * $stateProvider.state("home", {
  *   template: "<h1>HELLO!</h1>"
  * })
  * ```
  *
- * The above is a convenient shortcut equivalent to specifying your view explicitly with the {@link ui.router.state.$stateProvider#views `views`}
- * config property, by name, in this case an empty name:
- * ```js
+ * The above is a convenient shortcut equivalent to specifying your view explicitly with the
+ * [[Ng1StateDeclaration.views]] config property, by name, in this case an empty name:
  *
+ * ```js
  * $stateProvider.state("home", {
  *   views: {
  *     "": {
@@ -88,12 +87,10 @@ export type UIViewAnimData = {
  * but you could if you wanted, like so:
  *
  * ```html
- *
  * <div ui-view="main"></div>
  * ```
  *
  * ```js
- *
  * $stateProvider.state("home", {
  *   views: {
  *     "main": {
@@ -104,8 +101,8 @@ export type UIViewAnimData = {
  * ```
  *
  * Really though, you'll use views to set up multiple views:
- * ```html
  *
+ * ```html
  * <div ui-view></div>
  * <div ui-view="chart"></div>
  * <div ui-view="data"></div>
@@ -127,10 +124,8 @@ export type UIViewAnimData = {
  * })
  * ```
  *
- * Examples for `autoscroll`:
- *
+ * #### Examples for `autoscroll`:
  * ```html
- *
  * <!-- If autoscroll present with no expression,
  *      then scroll ui-view into view -->
  * <ui-view autoscroll/>
@@ -145,7 +140,7 @@ export type UIViewAnimData = {
  * Resolve data:
  *
  * The resolved data from the state's `resolve` block is placed on the scope as `$resolve` (this
- * can be customized using [[ViewDeclaration.resolveAs]]).  This can be then accessed from the template.
+ * can be customized using [[Ng1ViewDeclaration.resolveAs]]).  This can be then accessed from the template.
  *
  * Note that when `controllerAs` is being used, `$resolve` is set on the controller instance *after* the
  * controller is instantiated.  The `$onInit()` hook can be used to perform initialization code which
@@ -161,7 +156,7 @@ export type UIViewAnimData = {
  * });
  * ```
  */
-let uiView: ng1_directive;
+export let uiView: ng1_directive;
 uiView = ['$view', '$animate', '$uiViewScroll', '$interpolate', '$q',
 function $ViewDirective($view: ViewService, $animate: any, $uiViewScroll: any, $interpolate: IInterpolateService, $q: $QLike) {
 

src/injectables.ts

@@ -68,7 +68,7 @@ import { UrlRouterProvider } from "./urlRouterProvider";
  *
  * **Also:** an injectable **Per-Transition Object** object which holds the pending state parameters for the pending `Transition` currently running.
  *
- * ## Deprecation warning:
+ * ### Deprecation warning:
  *
  * The value injected for `$stateParams` is different depending on where it is injected.
  *
@@ -77,7 +77,7 @@ import { UrlRouterProvider } from "./urlRouterProvider";
  *
  * Because of these confusing details, this service is deprecated.
  *
- * @deprecated Instead of using the global `$stateParams` service object,
+ * ### Instead of using the global `$stateParams` service object,
  * inject [[$uiRouterGlobals]] and use [[UIRouterGlobals.params]]
  *
  * ```js
@@ -91,7 +91,7 @@ import { UrlRouterProvider } from "./urlRouterProvider";
  * }
  * ```
  *
- * @deprecated Instead of using the per-transition `$stateParams` object,
+ * ### Instead of using the per-transition `$stateParams` object,
  * inject the current `Transition` (as [[$transition$]]) and use [[Transition.params]]
  *
  * ```js
@@ -118,6 +118,7 @@ import { UrlRouterProvider } from "./urlRouterProvider";
  * };
  * angular.service('SomeService', SomeService);
  * ```
+ * @deprecated
  */
 var $stateParams: StateParams;
 
@@ -279,7 +280,7 @@ var $uiViewScrollProvider: UIViewScrollProvider;
  * If you prefer to rely on `$anchorScroll` to scroll the view to the anchor,
  * this can be enabled by calling [[UIViewScrollProvider.useAnchorScroll]].
  *
- * Note: this function is used by the [[uiView]] when the `autoscroll` expression evaluates to true.
+ * Note: this function is used by the [[directives.uiView]] when the `autoscroll` expression evaluates to true.
  */
 var $uiViewScroll: ($element: JQuery) => void;
 
@@ -305,8 +306,9 @@ var $stateProvider: StateProvider;
  * A service used to configure and interact with the URL.
  * It has URL related APIs including:
  *
- * - add URL rules [[UrlService.rules.when]]
- * - configure behavior when no url matches [[UrlService.rules.otherwise]]
+ * - register custom Parameter types `UrlService.config.type` ([[UrlConfigApi.type]])
+ * - add URL rules: `UrlService.rules.when` ([[UrlRulesApi.when]])
+ * - configure behavior when no url matches: `UrlService.rules.otherwise` ([[UrlRulesApi.otherwise]])
  * - delay initial URL synchronization [[UrlService.deferIntercept]].
  * - get or set the current url: [[UrlService.url]]
  *
@@ -324,9 +326,9 @@ var $urlServiceProvider: UrlService;
  * Used to configure the URL.
  * It has URL related APIs including:
  *
- * - register custom Parameter types [[UrlService.rules.when]]
- * - add URL rules [[UrlService.rules.when]]
- * - configure behavior when no url matches [[UrlService.rules.otherwise]]
+ * - register custom Parameter types `UrlService.config.type` ([[UrlConfigApi.type]])
+ * - add URL rules: `UrlService.rules.when` ([[UrlRulesApi.when]])
+ * - configure behavior when no url matches: `UrlService.rules.otherwise` ([[UrlRulesApi.otherwise]])
  * - delay initial URL synchronization [[UrlService.deferIntercept]].
  * - get or set the current url: [[UrlService.url]]
  *
@@ -337,48 +339,56 @@ var $urlService: UrlService;
 /**
  * The URL Router Provider
  *
+ * ### Deprecation warning: This object is now considered internal. Use [[$urlServiceProvider]] instead.
+ *
  * The [[UrlRouter]] singleton as a **Provider Object** (injectable during config time).
  *
  * #### Note: This object is also exposed as [[$urlRouter]] for injection during runtime.
  *
- * @deprecated This object is now considered internal. Use [[$urlServiceProvider]] instead.
+ * @deprecated
  */
 var $urlRouterProvider: UrlRouterProvider;
 
 /**
  * The Url Router
  *
+ * ### Deprecation warning: This object is now considered internal. Use [[$urlService]] instead.
+ *
  * The [[UrlRouter]] singleton as a **Service Object** (injectable during runtime).
  *
  * #### Note: This object is also exposed as [[$urlRouterProvider]] for injection during angular config time.
  *
- * @deprecated This object is now considered internal. Use [[$urlService]] instead.
+ * @deprecated
  */
 var $urlRouter: UrlRouter;
 
 /**
  * The URL Matcher Factory
  *
+ * ### Deprecation warning: This object is now considered internal. Use [[$urlService]] instead.
+ *
  * The [[UrlMatcherFactory]] singleton as a **Service Object** (injectable during runtime).
  *
  * This service is used to set url mapping options, define custom parameter types, and create [[UrlMatcher]] objects.
  *
  * #### Note: This object is also exposed as [[$urlMatcherFactoryProvider]] for injection during angular config time.
  *
- * @deprecated This object is now considered internal. Use [[$urlService]] instead.
+ * @deprecated
  */
 var $urlMatcherFactory: UrlMatcherFactory;
 
 /**
  * The URL Matcher Factory
  *
+ * ### Deprecation warning: This object is now considered internal. Use [[$urlService]] instead.
+ *
  * The [[UrlMatcherFactory]] singleton as a **Provider Object** (injectable during config time).
  *
  * This service is used to set url mapping options, define custom parameter types, and create [[UrlMatcher]] objects.
  *
  * #### Note: This object is also exposed as [[$urlMatcherFactory]] for injection during runtime.
  *
- * @deprecated This object is now considered internal. Use [[$urlService]] instead.
+ * @deprecated
  */
 var $urlMatcherFactoryProvider: UrlMatcherFactory;
 

src/interface.ts

@@ -163,10 +163,8 @@ export interface Ng1StateDeclaration extends StateDeclaration, Ng1ViewDeclaratio
    *
    * You can anchor the `ui-view` name to a specific state by including an `@`
    *
-   * @example
-   *
+   * #### Example:
    * ```js
-   *
    * // target the `<div ui-view='foo'></div>` which was created in a
    * // view owned by the state `bar.baz`
    * views: { 'foo@bar.baz': {...} }
@@ -270,7 +268,9 @@ export interface Ng1StateDeclaration extends StateDeclaration, Ng1ViewDeclaratio
   /**
    * Makes all search/query parameters `dynamic`
    *
-   * @deprecated use [[ParamDeclaration.dynamic]]
+   * ### Deprecation warning: use [[ParamDeclaration.dynamic]] instead
+   *
+   * @deprecated
    */
   reloadOnSearch?: boolean;
 }
@@ -400,7 +400,7 @@ export interface Ng1ViewDeclaration extends _ViewDeclaration {
    * A property of [[Ng1StateDeclaration]] or [[Ng1ViewDeclaration]]:
    *
    * The controller function, or the name of a registered controller.  The controller function will be used
-   * to control the contents of the [[ui-view]] directive.
+   * to control the contents of the [[directives.uiView]] directive.
    *
    * If specified as a string, controllerAs can be declared here, i.e., "FooController as foo" instead of in
    * a separate [[controllerAs]] property.
@@ -463,7 +463,7 @@ export interface Ng1ViewDeclaration extends _ViewDeclaration {
    * A property of [[Ng1StateDeclaration]] or [[Ng1ViewDeclaration]]:
    *
    * HTML template as a string, or a function which returns an html template as a string.
-   * This template will be used to render the corresponding [[ui-view]] directive.
+   * This template will be used to render the corresponding [[directives.uiView]] directive.
    *
    * This property takes precedence over templateUrl.
    *
@@ -489,7 +489,7 @@ export interface Ng1ViewDeclaration extends _ViewDeclaration {
    * A property of [[Ng1StateDeclaration]] or [[Ng1ViewDeclaration]]:
    *
    * A path or a function that returns a path to an html template.
-   * The template will be fetched and used to render the corresponding [[ui-view]] directive.
+   * The template will be fetched and used to render the corresponding [[directives.uiView]] directive.
    *
    * If `templateUrl` is a function, it will be called with the Transition parameters as the first argument.
    *
@@ -513,7 +513,7 @@ export interface Ng1ViewDeclaration extends _ViewDeclaration {
    * A property of [[Ng1StateDeclaration]] or [[Ng1ViewDeclaration]]:
    *
    * Injected function which returns the HTML template.
-   * The template will be used to render the corresponding [[ui-view]] directive.
+   * The template will be used to render the corresponding [[directives.uiView]] directive.
    *
    * #### Example:
    * ```js
@@ -558,9 +558,8 @@ export interface Ng1Controller {
    * @param newValues an object containing the changed parameter values
    * @param $transition$ the new Transition which triggered this callback
    *
-   * @example:
+   * #### Example:
    * ```js
-   *
    * angular.module('foo').controller('FancyCtrl', function() {
    *   this.uiOnParamsChanged = function(newParams) {
    *     console.log("new params: ", newParams);

src/legacy/resolveService.ts

@@ -38,7 +38,7 @@ var $resolve = {
    * // { id: 456, barData: 'bar data' }
    * ```
    *
-   * @param invocables an object which looks like an [[StateDefinition.resolve]] object; keys are resolve names and values are injectable functions
+   * @param invocables an object which looks like an [[StateDeclaration.resolve]] object; keys are resolve names and values are injectable functions
    * @param locals key/value pre-resolved data (locals)
    * @param parent a promise for a "parent resolve"
    */