feat(core/create): adds descriptions to all create functions

packages/core/src/create/application/index.ts

@@ -15,6 +15,13 @@ import { catchError } from 'rxjs/operators';
 import { throwError } from 'rxjs';
 import { PublicError, CollectionError } from '~/errors';
 
+/**
+ * Returns a new object instance of a collection; prepares a collection to be used by an adapter:
+ * - Pipes all services intercepts with their resolve function and merges their error types.
+ * - Ensures all services throw with a `PublicError`.
+ * - Checks for non-existent type references and references of the wrong kind.
+ * - Moves all inline types to `CollectionTree.types`.
+ */
 export default function application(
   collection: CollectionTree,
   options?: CreateApplicationOptions

packages/core/src/create/collections.ts

@@ -157,6 +157,9 @@ function collections<
   C49 &
   C50;
 
+/**
+ * Merges collections.
+ */
 function collections(
   ...collections: InputCollection[]
 ): CollectionTreeImplementation {

packages/core/src/create/intercepts.ts

@@ -16,6 +16,9 @@ import {
   isServiceImplementation
 } from '~/utils';
 
+/**
+ * Adds `intercepts` to all `ServiceImplementation`s of a given collection.
+ */
 export function intercepts<T extends CollectionTree>(
   collection: T,
   intercepts: InterceptImplementation[],
@@ -41,6 +44,9 @@ export function intercepts<T extends CollectionTree>(
   return collection;
 }
 
+/**
+ * Creates an intercept.
+ */
 export function intercept<I, O>(
   intercept: InputIntercept<I, O>
 ): InterceptImplementation<I, O> {
@@ -61,6 +67,9 @@ export function intercept<I, O>(
   };
 }
 
+/**
+ * Exposes a simpler api to create intercepts to be run *before* the `resolve` function of a `ServiceImplementation` has been called to act on the incoming `data`.
+ */
 export function before<T>(
   hook: InputInterceptHook<T>
 ): InterceptImplementation<T, any> {
@@ -79,6 +88,9 @@ export function before<T>(
   };
 }
 
+/**
+ * Exposes a simpler api to create intercepts to be run *after* the `resolve` function of a `ServiceImplementation` has been called to act on the outgoing `data`.
+ */
 export function after<T>(
   hook: InputInterceptHook<T>
 ): InterceptImplementation<any, T> {

packages/core/src/create/references.ts

@@ -6,6 +6,9 @@ export function references<
   K extends keyof T['types']
 >(collection: T, names?: K[]): { [P in K]: P };
 
+/**
+ * Returns an object with *keys* and *values* of `names`. It is essentially a helper to be used for type safety when referencing error types on service creation.
+ */
 export function references(
   a: CollectionTree | string[],
   b?: string[]
@@ -32,6 +35,9 @@ export function references(
   }
 }
 
+/**
+ * Returns a *string* equal to `name`. It is essentially a helper to be used for type safety when referencing request and response types on service creation.
+ */
 export function reference<T extends CollectionTree, K extends keyof T['types']>(
   collection: T,
   name: K

packages/core/src/create/schema.ts

@@ -1,5 +1,8 @@
 import { Schema } from '~/types';
 
+/**
+ * Returns the input `schema`, as a type `'object'` if it was not specified. It exists to serve as a helper to improve type inference.
+ */
 export default function schema(schema: Schema = {}): Schema {
   return {
     type: schema.type || 'object',

packages/core/src/create/scopes.ts

@@ -1,6 +1,9 @@
 import { ScopeCreate, CollectionTree, ExtractScopeCreate } from '~/types';
 import { emptyCollection, emptyScope } from '~/utils';
 
+/**
+ * Given a `collection`, returs a new collection with all of the services within the input collection in scope `name`.
+ */
 export function scope<T extends CollectionTree, N extends string>(
   name: N,
   collection: T
@@ -16,6 +19,9 @@ export function scope<T extends CollectionTree, N extends string>(
   } as any;
 }
 
+/**
+ * Given a collection with a scope `name`, returns a new collection with all of the services in the root scope of the input collection discarded, and scope `name` serving as the new collection root.
+ */
 export function extract<T extends CollectionTree, N extends keyof T['scopes']>(
   collection: T,
   name: N & string

packages/core/src/create/services.ts

@@ -16,6 +16,9 @@ import { switchMap } from 'rxjs/operators';
 import { request, response } from './types';
 import { isElement } from '~/utils';
 
+/**
+ * Returns a new `collection` with services `services`.
+ */
 export function services<T extends TreeServicesImplementation>(
   services: T
 ): CollectionTreeImplementation<{}, T, {}> {
@@ -29,6 +32,9 @@ export function services<T extends TreeServicesImplementation>(
   };
 }
 
+/**
+ * Creates a `QueryServiceImplementation`.
+ */
 export function query<I, O>(
   query: InputQueryService<I, O>
 ): QueryServiceImplementation<I, O> {
@@ -43,6 +49,9 @@ export function query<I, O>(
   };
 }
 
+/**
+ * Creates a `MutationServiceImplementation`.
+ */
 export function mutation<I, O>(
   mutation: InputMutationService<I, O>
 ): MutationServiceImplementation<I, O> {
@@ -57,6 +66,9 @@ export function mutation<I, O>(
   };
 }
 
+/**
+ * Creates a `MutationServiceImplementation`.
+ */
 export function subscription<I, O>(
   subscription: InputSubscriptionService<I, O>
 ): SubscriptionServiceImplementation<I, O> {

packages/core/src/create/types.ts

@@ -9,6 +9,9 @@ import {
   CollectionTreeImplementation
 } from '~/types';
 
+/**
+ * Returns a new `collection` with types `types`.
+ */
 export function types<T extends TreeTypesImplementation>(
   types: T
 ): CollectionTreeImplementation<T, {}, {}> {
@@ -20,20 +23,29 @@ export function types<T extends TreeTypesImplementation>(
   };
 }
 
+/**
+ * Creates an `ErrorTypeImplementation`.
+ */
 export function error(error: InputErrorType): ErrorTypeImplementation {
   return {
     kind: 'error',
     ...error
   };
 }
 
+/**
+ * Creates a `RequestTypeImplementation`.
+ */
 export function request(request: InputRequestType): RequestTypeImplementation {
   return {
     kind: 'request',
     ...request
   };
 }
 
+/**
+ * Creates a `ResponseTypeImplementation`.
+ */
 export function response(
   response: InputResponseType
 ): ResponseTypeImplementation {