doc: Migrate to typedoc generation via docgen tool

- Remove all @module annotations and most @packageDocumentation (each file gets its own module)
- Manually construct navigation via new typedoc-plugin-ui-router

Author: christopherthielen

docgen.json

@@ -0,0 +1,12 @@
+{
+  "publishDir": "_core_docs",
+  "include": [],
+  "tsconfig": {
+    "compilerOptions": {}
+  },
+  "navigation": {
+    "": ["UIRouter"],
+    "Services": ["StateService", "StateRegistry", "TransitionService", "UrlService", "UrlConfig", "UrlRules"],
+    "Other": ["Transition", "Trace"]
+  }
+}

src/common/common.ts

@@ -3,7 +3,8 @@
  *
  * These functions are exported, but are subject to change without notice.
  *
- * @packageDocumentation @preferred @publicapi @module common
+ * @packageDocumentation
+ * @preferred
  */
 import { isFunction, isString, isArray, isRegExp, isDate } from './predicates';
 import { all, any, prop, curry, not } from './hof';
@@ -57,8 +58,6 @@ export type PredicateBinary<X, Y> = (x?: X, y?: Y) => boolean;
  *
  * }];
  * ```
- *
- * @publicapi
  */
 export type IInjectable = Function | any[];
 
@@ -129,9 +128,9 @@ export function createProxyFunctions(
   fnNames?: string[],
   latebind = false
 ): Obj {
-  const bindFunction = fnName => source()[fnName].bind(bind());
+  const bindFunction = (fnName) => source()[fnName].bind(bind());
 
-  const makeLateRebindFn = fnName =>
+  const makeLateRebindFn = (fnName) =>
     function lateRebindFunction() {
       target[fnName] = bindFunction(fnName);
       return target[fnName].apply(null, arguments);
@@ -182,7 +181,7 @@ export function _pushTo(arr, val?): any {
 
 /** Given an array of (deregistration) functions, calls all functions and removes each one from the source array */
 export const deregAll = (functions: Function[]) =>
-  functions.slice().forEach(fn => {
+  functions.slice().forEach((fn) => {
     typeof fn === 'function' && fn();
     removeFrom(functions, fn);
   });
@@ -275,8 +274,8 @@ export function filter<T>(collection: TypedMap<T>, callback: (t: T, key?: string
 export function filter<T>(collection: any, callback: Function): T {
   const arr = isArray(collection),
     result: any = arr ? [] : {};
-  const accept = arr ? x => result.push(x) : (x, key) => (result[key] = x);
-  forEach(collection, function(item, i) {
+  const accept = arr ? (x) => result.push(x) : (x, key) => (result[key] = x);
+  forEach(collection, function (item, i) {
     if (callback(item, i)) accept(item, i);
   });
   return <T>result;
@@ -290,7 +289,7 @@ export function find<T>(collection: T[], callback: Predicate<T>): T;
 export function find(collection: any, callback: any) {
   let result;
 
-  forEach(collection, function(item, i) {
+  forEach(collection, function (item, i) {
     if (result) return;
     if (callback(item, i)) result = item;
   });
@@ -328,7 +327,7 @@ export function map(collection: any, callback: any, target: typeof collection):
  * let vals = values(foo); // [ 1, 2, 3 ]
  * ```
  */
-export const values: (<T>(obj: TypedMap<T>) => T[]) = (obj: Obj) => Object.keys(obj).map(key => obj[key]);
+export const values: <T>(obj: TypedMap<T>) => T[] = (obj: Obj) => Object.keys(obj).map((key) => obj[key]);
 
 /**
  * Reduce function that returns true if all of the values are truthy.
@@ -451,7 +450,7 @@ export const assertPredicate: <T>(predicate: Predicate<T>, errMsg: string | Func
  */
 export const assertMap: <T, U>(mapFn: (t: T) => U, errMsg: string | Function) => (t: T) => U = assertFn;
 export function assertFn(predicateOrMap: Function, errMsg: string | Function = 'assert failure'): any {
-  return obj => {
+  return (obj) => {
     const result = predicateOrMap(obj);
     if (!result) {
       throw new Error(isFunction(errMsg) ? (<Function>errMsg)(obj) : errMsg);
@@ -469,7 +468,7 @@ export function assertFn(predicateOrMap: Function, errMsg: string | Function = '
  * pairs({ foo: "FOO", bar: "BAR }) // [ [ "foo", "FOO" ], [ "bar": "BAR" ] ]
  * ```
  */
-export const pairs = (obj: Obj) => Object.keys(obj).map(key => [key, obj[key]]);
+export const pairs = (obj: Obj) => Object.keys(obj).map((key) => [key, obj[key]]);
 
 /**
  * Given two or more parallel arrays, returns an array of tuples where
@@ -507,7 +506,7 @@ export function arrayTuples(...args: any[]): any[] {
         result.push([args[0][i], args[1][i], args[2][i], args[3][i]]);
         break;
       default:
-        result.push(args.map(array => array[i]));
+        result.push(args.map((array) => array[i]));
         break;
     }
   }
@@ -552,15 +551,15 @@ export function tail<T>(arr: T[]): T {
  * shallow copy from src to dest
  */
 export function copy(src: Obj, dest?: Obj) {
-  if (dest) Object.keys(dest).forEach(key => delete dest[key]);
+  if (dest) Object.keys(dest).forEach((key) => delete dest[key]);
   if (!dest) dest = {};
   return extend(dest, src);
 }
 
 /** Naive forEach implementation works with Objects or Arrays */
 function _forEach(obj: any[] | any, cb: (el, idx?) => void, _this: Obj) {
   if (isArray(obj)) return obj.forEach(cb, _this);
-  Object.keys(obj).forEach(key => cb(obj[key], key));
+  Object.keys(obj).forEach((key) => cb(obj[key], key));
 }
 
 /** Like Object.assign() */
@@ -615,5 +614,5 @@ function _arraysEq(a1: any[], a2: any[]) {
 }
 
 // issue #2676
-export const silenceUncaughtInPromise = (promise: Promise<any>) => promise.catch(e => 0) && promise;
+export const silenceUncaughtInPromise = (promise: Promise<any>) => promise.catch((e) => 0) && promise;
 export const silentRejection = (error: any) => silenceUncaughtInPromise(services.$q.reject(error));

src/common/coreservices.ts

@@ -2,7 +2,7 @@
  * This module is a stub for core services such as Dependency Injection or Browser Location.
  * Core services may be implemented by a specific framework, such as ng1 or ng2, or be pure javascript.
  *
- * @packageDocumentation @publicapi @module common
+ * @packageDocumentation
  */
 import { IInjectable, Obj } from './common';
 import { Disposable } from '../interface';

src/common/glob.ts

@@ -1,4 +1,3 @@
-/** @packageDocumentation @publicapi @module core */
 /**
  * Matches state names using glob-like pattern strings.
  *
@@ -46,6 +45,7 @@
  * | `'**.X'`    | `'X'` , `'A.X'` , `'Z.Y.X'`                   | `'A'` , `'A.login.Z'`             |
  * | `'A.**.X'`  | `'A.X'` , `'A.B.X'` , `'A.B.C.X'`             | `'A'` , `'A.B.C'`                 |
  *
+ * @packageDocumentation
  */
 export class Glob {
   text: string;
@@ -68,7 +68,7 @@ export class Glob {
 
     const regexpString = this.text
       .split('.')
-      .map(seg => {
+      .map((seg) => {
         if (seg === '**') return '(?:|(?:\\.[^.]*)*)';
         if (seg === '*') return '\\.[^.]*';
         return '\\.' + seg;

src/common/hof.ts

@@ -3,7 +3,7 @@
  *
  * These utility functions are exported, but are subject to change without notice.
  *
- * @packageDocumentation @module common_hof
+ * @packageDocumentation
  */
 
 import { Predicate } from './common';
@@ -67,7 +67,7 @@ export function curry(fn: Function): Function {
 export function compose() {
   const args = arguments;
   const start = args.length - 1;
-  return function() {
+  return function () {
     let i = start,
       result = args[start].apply(this, arguments);
     while (i--) result = args[i].call(this, result);
@@ -203,7 +203,7 @@ export function invoke(fnName: string, args?: any[]): Function {
  * @returns {function(any): *}
  */
 export function pattern(struct: Function[][]): Function {
-  return function(x: any) {
+  return function (x: any) {
     for (let i = 0; i < struct.length; i++) {
       if (struct[i][0](x)) return struct[i][1](x);
     }

src/common/index.ts

@@ -1,4 +1,3 @@
-/** @packageDocumentation @publicapi @module common */
 export * from './common';
 export * from './coreservices';
 export * from './glob';

src/common/predicates.ts

@@ -1,9 +1,10 @@
-/** Predicates
+/**
+ * Predicates
  *
  * These predicates return true/false based on the input.
  * Although these functions are exported, they are subject to change without notice.
  *
- * @packageDocumentation @module common_predicates
+ * @packageDocumentation
  */
 import { and, not, pipe, prop, or } from './hof';
 import { Predicate } from './common'; // has or is using
@@ -43,10 +44,4 @@ export function isInjectable(val: any) {
  *
  * It is probably a Promise if it's an object, and it has a `then` property which is a Function
  */
-export const isPromise = <(x: any) => x is Promise<any>>and(
-  isObject,
-  pipe(
-    prop('then'),
-    isFunction
-  )
-);
+export const isPromise = <(x: any) => x is Promise<any>>and(isObject, pipe(prop('then'), isFunction));

src/common/queue.ts

@@ -1,4 +1,3 @@
-/** @packageDocumentation @publicapi @module common */
 import { pushTo } from './common';
 
 export class Queue<T> {
@@ -16,7 +15,7 @@ export class Queue<T> {
 
   evict(): T {
     const item: T = this._items.shift();
-    this._evictListeners.forEach(fn => fn(item));
+    this._evictListeners.forEach((fn) => fn(item));
     return item;
   }
 

src/common/safeConsole.ts

@@ -1,6 +1,6 @@
 /**
  * workaround for missing console object in IE9 when dev tools haven't been opened o_O
- * @packageDocumentation @module core
+ * @packageDocumentation
  */
 /* tslint:disable:no-console */
 import { noop } from './common';

src/common/strings.ts

@@ -3,7 +3,7 @@
  *
  * Although these functions are exported, they are subject to change without notice.
  *
- * @packageDocumentation @module common_strings
+ * @packageDocumentation
  */
 
 import { isArray, isFunction, isInjectable, isNull, isObject, isPromise, isString, isUndefined } from './predicates';
@@ -41,8 +41,8 @@ export function padString(length: number, str: string) {
 
 export function kebobString(camelCase: string) {
   return camelCase
-    .replace(/^([A-Z])/, $1 => $1.toLowerCase()) // replace first char
-    .replace(/([A-Z])/g, $1 => '-' + $1.toLowerCase()); // replace rest
+    .replace(/^([A-Z])/, ($1) => $1.toLowerCase()) // replace first char
+    .replace(/([A-Z])/g, ($1) => '-' + $1.toLowerCase()); // replace rest
 }
 
 export function functionToString(fn: Function) {