Add @category JSDoc tag to improve reference docs generation (sindres…

…orhus#209)

source/async-return-type.d.ts

@@ -19,5 +19,7 @@ async function doSomething(value: Value) {}
 
 asyncFunction().then(value => doSomething(value));
 ```
+
+@category Utilities
 */
 export type AsyncReturnType<Target extends AsyncFunction> = PromiseValue<ReturnType<Target>>;

source/asyncify.d.ts

@@ -27,5 +27,7 @@ const getFooAsync: AsyncifiedFooGetter = (someArg) => {
 	// …
 }
 ```
+
+@category Utilities
 */
 export type Asyncify<Fn extends (...args: any[]) => any> = SetReturnType<Fn, Promise<PromiseValue<ReturnType<Fn>>>>;

source/basic.d.ts

@@ -1,24 +1,32 @@
 // TODO: Remove the `= unknown` sometime  in the future when most users are on TS 3.5 as it's now the default
 /**
 Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
+
+@category Basic
 */
 export type Class<T = unknown, Arguments extends any[] = any[]> = new(...arguments_: Arguments) => T;
 
 /**
 Matches a JSON object.
 
 This type can be useful to enforce some input to be JSON-compatible or as a super-type to be extended from. Don't use this as a direct return type as the user would have to double-cast it: `jsonObject as unknown as CustomResponse`. Instead, you could extend your CustomResponse type from it to ensure your type only uses JSON-compatible types: `interface CustomResponse extends JsonObject { … }`.
+
+@category Basic
 */
 export type JsonObject = {[Key in string]?: JsonValue};
 
 /**
 Matches a JSON array.
+
+@category Basic
 */
 export interface JsonArray extends Array<JsonValue> {}
 // TODO: Make it this when targeting TypeScript 4.1:
 // export type JsonArray = JsonValue[];
 
 /**
 Matches any valid JSON value.
+
+@category Basic
 */
 export type JsonValue = string | number | boolean | null | JsonObject | JsonArray;

source/conditional-except.d.ts

@@ -36,6 +36,8 @@ interface Example {
 type NonStringKeysOnly = ConditionalExcept<Example, string>;
 //=> {b: string | number; c: () => void; d: {}}
 ```
+
+@category Utilities
 */
 export type ConditionalExcept<Base, Condition> = Except<
 	Base,

source/conditional-keys.d.ts

@@ -25,6 +25,8 @@ To support partial types, make sure your `Condition` is a union of undefined (fo
 type StringKeysAndUndefined = ConditionalKeys<Example, string | undefined>;
 //=> 'a' | 'c'
 ```
+
+@category Utilities
 */
 export type ConditionalKeys<Base, Condition> = NonNullable<
 	// Wrap in `NonNullable` to strip away the `undefined` type from the produced union.

source/conditional-pick.d.ts

@@ -35,6 +35,8 @@ interface Example {
 type StringKeysOnly = ConditionalPick<Example, string>;
 //=> {a: string}
 ```
+
+@category Utilities
 */
 export type ConditionalPick<Base, Condition> = Pick<
 	Base,

source/entries.d.ts

@@ -48,6 +48,8 @@ const mapEntries: Entries<typeof map> = [['a', 1]];
 const setExample = new Set(['a', 1]);
 const setEntries: Entries<typeof setExample> = [['a', 'a'], [1, 1]];
 ```
+
+@category Utilities
 */
 export type Entries<BaseType> =
 	BaseType extends Map<unknown, unknown> ? MapEntries<BaseType>

source/entry.d.ts

@@ -51,6 +51,8 @@ const setExample = new Set(['a', 1]);
 const setEntryString: Entry<typeof setExample> = ['a', 'a'];
 const setEntryNumber: Entry<typeof setExample> = [1, 1];
 ```
+
+@category Utilities
 */
 export type Entry<BaseType> =
 	BaseType extends Map<unknown, unknown> ? MapEntry<BaseType>

source/except.d.ts

@@ -18,5 +18,7 @@ type Foo = {
 type FooWithoutA = Except<Foo, 'a' | 'c'>;
 //=> {b: string};
 ```
+
+@category Utilities
 */
 export type Except<ObjectType, KeysType extends keyof ObjectType> = Pick<ObjectType, Exclude<keyof ObjectType, KeysType>>;

source/fixed-length-array.d.ts

@@ -27,6 +27,8 @@ const homeFencingTeam: FencingTeam = ['George', 'John'];
 guestFencingTeam.push('Sam');
 //=> error TS2339: Property 'push' does not exist on type 'FencingTeam'
 ```
+
+@category Utilities
 */
 export type FixedLengthArray<Element, Length extends number, ArrayPrototype = [Element, ...Element[]]> = Pick<
 	ArrayPrototype,

source/iterable-element.d.ts

@@ -37,6 +37,8 @@ An example with an array of strings:
 ```
 type MeString = IterableElement<string[]>
 ```
+
+@category Utilities
 */
 export type IterableElement<TargetIterable> =
 	TargetIterable extends Iterable<infer ElementType> ?

source/literal-union.d.ts

@@ -26,6 +26,8 @@ type Pet2 = LiteralUnion<'dog' | 'cat', string>;
 const pet: Pet2 = '';
 // You **will** get auto-completion for `dog` and `cat` literals.
 ```
+
+@category Utilities
  */
 export type LiteralUnion<
 	LiteralType,

source/merge-exclusive.d.ts

@@ -31,6 +31,8 @@ exclusiveOptions = {exclusive2: 'hi'};
 exclusiveOptions = {exclusive1: true, exclusive2: 'hi'};
 //=> Error
 ```
+
+@category Utilities
 */
 export type MergeExclusive<FirstType, SecondType> =
 	(FirstType | SecondType) extends object ?

source/merge.d.ts

@@ -21,5 +21,7 @@ type Bar = {
 
 const ab: Merge<Foo, Bar> = {a: 1, b: 2};
 ```
+
+@category Utilities
 */
 export type Merge<FirstType, SecondType> = Simplify<Merge_<FirstType, SecondType>>;

source/mutable.d.ts

@@ -28,6 +28,8 @@ type SomeMutable = Mutable<Foo, 'b' | 'c'>;
 // 	c: boolean; // It's now mutable.
 // }
 ```
+
+@category Utilities
 */
 export type Mutable<BaseType, Keys extends keyof BaseType = keyof BaseType> =
 	Simplify<

source/observable-like.d.ts

@@ -6,6 +6,8 @@ declare global {
 
 /**
 Matches a value that is like an [Observable](https://github.com/tc39/proposal-observable).
+
+@category Basic
 */
 export interface ObservableLike {
 	subscribe(observer: (value: unknown) => void): void;

source/opaque.d.ts

@@ -61,5 +61,7 @@ type Person = {
 	name: string;
 };
 ```
+
+@category Utilities
 */
 export type Opaque<Type, Token = unknown> = Type & {readonly __opaque__: Token};

source/package-json.d.ts

@@ -629,6 +629,8 @@ declare namespace PackageJson {
 
 /**
 Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file). Also includes types for fields used by other popular projects, like TypeScript and Yarn.
+
+@category Miscellaneous
 */
 export type PackageJson =
 PackageJson.PackageJsonStandard &

source/partial-deep.d.ts

@@ -27,6 +27,8 @@ const applySavedSettings = (savedSettings: PartialDeep<Settings>) => {
 
 settings = applySavedSettings({textEditor: {fontWeight: 500}});
 ```
+
+@category Utilities
 */
 export type PartialDeep<T> = T extends Primitive
 	? Partial<T>

source/primitive.d.ts

@@ -1,5 +1,7 @@
 /**
 Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
+
+@category Basic
 */
 export type Primitive =
 	| null

source/promisable.d.ts

@@ -18,6 +18,8 @@ async function logger(getLogEntry: () => Promisable<string>): Promise<void> {
 
 logger(() => 'foo');
 logger(() => Promise.resolve('bar'));
+
+@category Utilities
 ```
 */
 export type Promisable<T> = T | PromiseLike<T>;

source/promise-value.d.ts

@@ -21,6 +21,8 @@ let syncData: SyncData = getSyncData();
 type RecursiveAsyncData = Promise<Promise<string> >;
 let recursiveAsyncData: PromiseValue<RecursiveAsyncData> = Promise.resolve(Promise.resolve('ABC'));
 ```
+
+@category Utilities
 */
 export type PromiseValue<PromiseType, Otherwise = PromiseType> = PromiseType extends Promise<infer Value>
 	? { 0: PromiseValue<Value>; 1: Value }[PromiseType extends Promise<unknown> ? 0 : 1]

source/readonly-deep.d.ts

@@ -28,6 +28,8 @@ import data from './main';
 data.foo.push('bar');
 //=> error TS2339: Property 'push' does not exist on type 'readonly string[]'
 ```
+
+@category Utilities
 */
 export type ReadonlyDeep<T> = T extends Primitive | ((...arguments: any[]) => unknown)
 	? T

source/require-at-least-one.d.ts

@@ -19,6 +19,8 @@ const responder: RequireAtLeastOne<Responder, 'text' | 'json'> = {
 	secure: true
 };
 ```
+
+@category Utilities
 */
 export type RequireAtLeastOne<
 	ObjectType,

source/require-exactly-one.d.ts

@@ -27,6 +27,8 @@ const responder: RequireExactlyOne<Responder, 'text' | 'json'> = {
 	secure: true
 };
 ```
+
+@category Utilities
 */
 export type RequireExactlyOne<ObjectType, KeysType extends keyof ObjectType = keyof ObjectType> =
 	{[Key in KeysType]: (

source/set-optional.d.ts

@@ -23,6 +23,8 @@ type SomeOptional = SetOptional<Foo, 'b' | 'c'>;
 // 	c?: boolean; // Is now optional.
 // }
 ```
+
+@category Utilities
 */
 export type SetOptional<BaseType, Keys extends keyof BaseType> =
 	Simplify<

source/set-required.d.ts

@@ -23,6 +23,8 @@ type SomeRequired = SetRequired<Foo, 'b' | 'c'>;
 // 	c: boolean; // Is now required.
 // }
 ```
+
+@category Utilities
 */
 export type SetRequired<BaseType, Keys extends keyof BaseType> =
 	Simplify<

source/set-return-type.d.ts

@@ -16,6 +16,8 @@ type MyFunctionThatCanThrow = (foo: SomeType, bar: unknown) => SomeOtherType;
 type MyWrappedFunction = SetReturnType<MyFunctionThatCanThrow, SomeOtherType | undefined>;
 //=> type MyWrappedFunction = (foo: SomeType, bar: unknown) => SomeOtherType | undefined;
 ```
+
+@category Utilities
 */
 export type SetReturnType<Fn extends (...args: any[]) => any, TypeToReturn> =
 	// Just using `Parameters<Fn>` isn't ideal because it doesn't handle the `this` fake parameter.

source/stringified.d.ts

@@ -17,5 +17,7 @@ const carForm: Stringified<Car> = {
 	speed: '101'
 };
 ```
+
+@category Utilities
 */
 export type Stringified<ObjectType> = {[KeyType in keyof ObjectType]: string};

source/tsconfig-json.d.ts

@@ -815,6 +815,11 @@ declare namespace TsConfigJson {
 	}
 }
 
+/**
+Type for [TypeScript's `tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) (TypeScript 3.7).
+
+@category Miscellaneous
+*/
 export interface TsConfigJson {
 	/**
 	Instructs the TypeScript compiler how to compile `.ts` files.

source/typed-array.d.ts

@@ -2,6 +2,8 @@
 
 /**
 Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
+
+@category Basic
 */
 export type TypedArray =
 	| Int8Array

source/union-to-intersection.d.ts

@@ -40,6 +40,8 @@ type Union = typeof union;
 type Intersection = UnionToIntersection<Union>;
 //=> {a1(): void; b1(): void; a2(argA: string): void; b2(argB: string): void}
 ```
+
+@category Utilities
 */
 export type UnionToIntersection<Union> = (
 	// `extends unknown` is always going to be the case and is used to convert the

source/value-of.d.ts

@@ -36,5 +36,7 @@ onlyBar('foo');
 onlyBar('bar');
 //=> 2
 ```
+
+@category Utilities
 */
 export type ValueOf<ObjectType, ValueType extends keyof ObjectType = keyof ObjectType> = ObjectType[ValueType];

ts41/camel-case.d.ts

@@ -60,5 +60,7 @@ const dbResult: CamelCasedProperties<ModelProps> = {
 	foo: 123
 };
 ```
+
+@category Template Literals
 */
 export type CamelCase<K> = K extends string ? CamelCaseStringArray<Split<K, WordSeparators>> : K;

ts41/camel-cased-properties-deep.d.ts

@@ -37,6 +37,8 @@ const result: CamelCasedPropertiesDeep<UserWithFriends> = {
 	],
 };
 ```
+
+@category Template Literals
 */
 export type CamelCasedPropertiesDeep<Value> = Value extends Function
 	? Value

ts41/camel-cased-properties.d.ts

@@ -20,6 +20,8 @@ const result: CamelCasedProperties<User> = {
 	userName: 'Tom',
 };
 ```
+
+@category Template Literals
 */
 export type CamelCasedProperties<Value> = Value extends Function
 	? Value

ts41/delimiter-case.d.ts

@@ -2,6 +2,8 @@ import {UpperCaseCharacters, WordSeparators} from '../source/utilities';
 
 /**
 Unlike a simpler split, this one includes the delimiter splitted on in the resulting array literal. This is to enable splitting on, for example, upper-case characters.
+
+@category Template Literals
 */
 export type SplitIncludingDelimiters<Source extends string, Delimiter extends string> =
 	Source extends '' ? [] :
@@ -73,8 +75,9 @@ const rawCliOptions: OddlyCasedProperties<SomeOptions> = {
 	foo: 123
 };
 ```
-*/
 
+@category Template Literals
+*/
 export type DelimiterCase<Value, Delimiter extends string> = Value extends string
 	? StringArrayToDelimiterCase<
 		SplitIncludingDelimiters<Value, WordSeparators | UpperCaseCharacters>,

ts41/delimiter-cased-properties-deep.d.ts

@@ -37,6 +37,8 @@ const result: DelimiterCasedPropertiesDeep<UserWithFriends, '-'> = {
 	],
 };
 ```
+
+@category Template Literals
 */
 export type DelimiterCasedPropertiesDeep<
 	Value,

ts41/delimiter-cased-properties.d.ts

@@ -20,6 +20,8 @@ const result: DelimiterCasedProperties<User, '-'> = {
 	'user-name': 'Tom',
 };
 ```
+
+@category Template Literals
 */
 export type DelimiterCasedProperties<
 	Value,

ts41/get.d.ts

@@ -127,5 +127,7 @@ const getName = (apiResponse: ApiResponse) =>
 	get(apiResponse, 'hits.hits[0]._source.name');
 	//=> Array<{given: string[]; family: string}>
 ```
+
+@category Template Literals
 */
 export type Get<BaseType, Path extends string> = GetWithPath<BaseType, ToPath<Path>>;

ts41/kebab-case.d.ts

@@ -31,6 +31,7 @@ const rawCliOptions: KebabCasedProperties<CliOptions> = {
 	foo: 123
 };
 ```
-*/
 
+@category Template Literals
+*/
 export type KebabCase<Value> = DelimiterCase<Value, '-'>;