docs: use inheritdocs where appropriate (#79)

.vscode/skunkteam-types-snippets.code-snippets

@@ -18,7 +18,13 @@
     "Exported type with @skunkteam/types": {
         "scope": "typescript",
         "prefix": "skunk-type",
-        "description": "Create a new exported type with @skunkteam/types including all boilerplate",
+        "description": "Create a new type with @skunkteam/types including all boilerplate",
         "body": ["type ${1:Name} = The<typeof $1>;", "const $1 = ${2:type}('$1', $0);"]
+    },
+    "Inherit docs": {
+        "scope": "typescript",
+        "prefix": "inherit",
+        "description": "Inherit docs from BaseTypeImpl class",
+        "body": "/** {@inheritdoc ${1|BaseTypeImpl,BaseObjectLikeTypeImpl|}.$0} */"
     }
 }

etc/types.api.md

@@ -9,20 +9,16 @@ export function array<Element>(...args: [name: string, elementType: BaseTypeImpl
 
 // @public
 export class ArrayType<ElementType extends BaseTypeImpl<Element>, Element, ResultType extends Element[]> extends BaseTypeImpl<ResultType, ArrayTypeConfig> {
-    constructor(elementType: ElementType, typeConfig: ArrayTypeConfig, name?: string);
-    // (undocumented)
+    constructor(elementType: ElementType,
+    typeConfig: ArrayTypeConfig, name?: string);
     accept<R>(visitor: Visitor<R>): R;
-    // (undocumented)
     readonly basicType: 'array';
     // (undocumented)
     readonly elementType: ElementType;
     // (undocumented)
     readonly isDefaultName: boolean;
-    // (undocumented)
     readonly name: string;
-    // (undocumented)
     readonly typeConfig: ArrayTypeConfig;
-    // (undocumented)
     protected typeValidator(input: unknown, options: ValidationOptions): Result<ResultType>;
 }
 
@@ -135,15 +131,13 @@ export const int: Type<Branded<number, 'int'>, NumberTypeConfig>;
 
 // @public
 export class InterfaceType<Props extends Properties, ResultType> extends BaseObjectLikeTypeImpl<ResultType> implements TypedPropertyInformation<Props> {
-    constructor(props: Props, options: InterfaceTypeOptions);
-    // (undocumented)
+    constructor(
+    props: Props, options: InterfaceTypeOptions);
     accept<R>(visitor: Visitor<R>): R;
-    // (undocumented)
     readonly basicType: 'object';
     // (undocumented)
     readonly isDefaultName: boolean;
     readonly keys: (keyof Props)[];
-    // (undocumented)
     readonly name: string;
     // (undocumented)
     readonly options: InterfaceTypeOptions;
@@ -157,9 +151,7 @@ export class InterfaceType<Props extends Properties, ResultType> extends BaseObj
     // (undocumented)
     readonly propsInfo: PropertiesInfo<Props>;
     toPartial(name?: string): PartialType<Props>;
-    // (undocumented)
     readonly typeConfig: undefined;
-    // (undocumented)
     protected typeValidator(input: unknown, options: ValidationOptions): Result<ResultType>;
     withOptional<PartialProps extends Properties>(...args: [props: PartialProps] | [name: string, props: PartialProps]): TypeImpl<BaseObjectLikeTypeImpl<MergeIntersection<ResultType & Partial<TypeOfProperties<Writable<PartialProps>>>>>> & TypedPropertyInformation<Props & PartialProps>;
 }
@@ -185,15 +177,12 @@ export type IntersectionOfTypeTuple<Tuple> = Tuple extends [{
 // @public
 export class IntersectionType<Types extends OneOrMore<BaseObjectLikeTypeImpl<unknown>>> extends BaseObjectLikeTypeImpl<IntersectionOfTypeTuple<Types>, undefined> implements TypedPropertyInformation<PropertiesOfTypeTuple<Types>> {
     constructor(types: Types, name?: string);
-    // (undocumented)
     accept<R>(visitor: Visitor<R>): R;
-    // (undocumented)
     readonly basicType: 'object';
     // (undocumented)
     readonly combinedName: string;
     // (undocumented)
     readonly isDefaultName: boolean;
-    // (undocumented)
     readonly name: string;
     // (undocumented)
     readonly possibleDiscriminators: Array<{
@@ -204,11 +193,9 @@ export class IntersectionType<Types extends OneOrMore<BaseObjectLikeTypeImpl<unk
     readonly props: PropertiesOfTypeTuple<Types>;
     // (undocumented)
     readonly propsInfo: PropertiesInfo<PropertiesOfTypeTuple<Types>>;
-    // (undocumented)
     readonly typeConfig: undefined;
     // (undocumented)
     readonly types: Types;
-    // (undocumented)
     protected typeValidator(input: unknown, options: ValidationOptions): Result<IntersectionOfTypeTuple<Types>>;
 }
 
@@ -220,22 +207,17 @@ export function keyof<T extends Record<string, unknown>>(...args: [name: string,
 
 // @public
 export class KeyofType<T extends Record<string, unknown>, ResultType extends keyof T = keyof T> extends BaseTypeImpl<ResultType> {
-    constructor(keys: T, name?: string);
-    // (undocumented)
+    constructor(keys: T,
+    name?: string);
     accept<R>(visitor: Visitor<R>): R;
-    // (undocumented)
     readonly basicType: 'string';
-    // (undocumented)
     readonly enumerableLiteralDomain: string[];
     // (undocumented)
     readonly keys: T;
-    // (undocumented)
     readonly name: string;
     // (undocumented)
     translate(input: unknown): T[keyof T];
-    // (undocumented)
     readonly typeConfig: undefined;
-    // (undocumented)
     protected typeValidator(input: unknown): Result<ResultType>;
 }
 
@@ -256,17 +238,11 @@ export function literal<T extends LiteralValue>(value: T): TypeImpl<LiteralType<
 // @public
 export class LiteralType<ResultType extends LiteralValue> extends BaseTypeImpl<ResultType> {
     constructor(value: ResultType);
-    // (undocumented)
     accept<R>(visitor: Visitor<R>): R;
-    // (undocumented)
     readonly basicType: BasicType;
-    // (undocumented)
     readonly enumerableLiteralDomain: ResultType[];
-    // (undocumented)
     readonly name: string;
-    // (undocumented)
     readonly typeConfig: undefined;
-    // (undocumented)
     protected typeValidator(input: unknown): Result<ResultType>;
     // (undocumented)
     readonly value: ResultType;
@@ -407,21 +383,16 @@ export function record<KeyType extends number | string, ValueType>(...args: [nam
 // @public
 export class RecordType<KeyTypeImpl extends BaseTypeImpl<KeyType>, KeyType extends number | string, ValueTypeImpl extends BaseTypeImpl<ValueType>, ValueType, ResultType extends Record<KeyType, ValueType> = Record<KeyType, ValueType>> extends BaseTypeImpl<ResultType> {
     constructor(keyType: KeyTypeImpl, valueType: ValueTypeImpl, name?: string, strict?: boolean);
-    // (undocumented)
     accept<R>(visitor: Visitor<R>): R;
-    // (undocumented)
     readonly basicType: 'object';
     // (undocumented)
     readonly isDefaultName: boolean;
     // (undocumented)
     readonly keyType: KeyTypeImpl;
-    // (undocumented)
     readonly name: string;
     // (undocumented)
     readonly strict: boolean;
-    // (undocumented)
     readonly typeConfig: undefined;
-    // (undocumented)
     protected typeValidator(input: unknown, options: ValidationOptions): Result<ResultType>;
     // (undocumented)
     readonly valueType: ValueTypeImpl;
@@ -436,17 +407,12 @@ export type Result<T> = Success<T> | Failure;
 
 // @public
 export class SimpleType<ResultType, TypeConfig> extends BaseTypeImpl<ResultType, TypeConfig> {
-    // (undocumented)
     accept<R>(visitor: Visitor<R>): R;
-    // (undocumented)
     readonly basicType: BasicType | 'mixed';
     static create<ResultType, TypeConfig>(name: string, basicType: BasicType | 'mixed', simpleValidator: (input: unknown, options: ValidationOptions, type: SimpleType<ResultType, TypeConfig>) => ValidationResult, options: SimpleTypeOptions<ResultType, TypeConfig>): Type<ResultType, TypeConfig>;
     static create<ResultType>(name: string, basicType: BasicType | 'mixed', simpleValidator: (input: unknown, options: ValidationOptions, type: SimpleType<ResultType, undefined>) => ValidationResult, options?: Omit<SimpleTypeOptions<ResultType, undefined>, 'typeConfig'>): Type<ResultType, undefined>;
-    // (undocumented)
     readonly name: string;
-    // (undocumented)
     readonly typeConfig: TypeConfig;
-    // (undocumented)
     protected typeValidator(input: unknown, options: ValidationOptions): Result<ResultType>;
 }
 
@@ -537,17 +503,13 @@ export function union<Types extends OneOrMore<BaseTypeImpl<unknown>>>(...args: [
 // @public
 export class UnionType<Types extends OneOrMore<BaseTypeImpl<unknown>>, ResultType extends TypeOf<Types[number]> = TypeOf<Types[number]>> extends BaseObjectLikeTypeImpl<ResultType> {
     constructor(types: Types, name?: string);
-    // (undocumented)
     accept<R>(visitor: Visitor<R>): R;
-    // (undocumented)
     readonly basicType: BasicType | "mixed";
     // (undocumented)
     readonly collapsedTypes: Types;
-    // (undocumented)
     readonly enumerableLiteralDomain: Set<LiteralValue> | undefined;
     // (undocumented)
     readonly isDefaultName: boolean;
-    // (undocumented)
     readonly name: string;
     // (undocumented)
     readonly possibleDiscriminators: {
@@ -558,11 +520,9 @@ export class UnionType<Types extends OneOrMore<BaseTypeImpl<unknown>>, ResultTyp
     readonly props: Properties;
     // (undocumented)
     readonly propsInfo: PropertiesInfo<Properties>;
-    // (undocumented)
     readonly typeConfig: undefined;
     // (undocumented)
     readonly types: Types;
-    // (undocumented)
     protected typeValidator(input: unknown, options: ValidationOptions): Result<ResultType>;
 }
 

markdown/types.arraytype._constructor_.md

@@ -9,7 +9,8 @@ Constructs a new instance of the `ArrayType` class
 **Signature:**
 
 ```typescript
-constructor(elementType: ElementType, typeConfig: ArrayTypeConfig, name?: string);
+constructor(elementType: ElementType,
+    typeConfig: ArrayTypeConfig, name?: string);
 ```
 
 ## Parameters

markdown/types.arraytype.accept.md

@@ -4,6 +4,8 @@
 
 ## ArrayType.accept() method
 
+Accept a visitor (visitor pattern).
+
 **Signature:**
 
 ```typescript
@@ -12,10 +14,14 @@ accept<R>(visitor: Visitor<R>): R;
 
 ## Parameters
 
-| Parameter | Type                                           | Description |
-| --------- | ---------------------------------------------- | ----------- |
-| visitor   | [Visitor](./types.visitor.md)<!-- -->&lt;R&gt; |             |
+| Parameter | Type                                           | Description           |
+| --------- | ---------------------------------------------- | --------------------- |
+| visitor   | [Visitor](./types.visitor.md)<!-- -->&lt;R&gt; | the visitor to accept |
 
 **Returns:**
 
 R
+
+## Remarks
+
+Note that, while it can be used to traverse a tree, this is not part of this pattern. The visitor that visits a particular type can decide to visit children of that type (or not). See `./testutils.ts` for an example.

markdown/types.arraytype.basictype.md

@@ -4,8 +4,14 @@
 
 ## ArrayType.basicType property
 
+The kind of values this type validates.
+
 **Signature:**
 
 ```typescript
 readonly basicType: 'array';
 ```
+
+## Remarks
+
+See [BasicType](./types.basictype.md) for more info about the rationale behind the basic type.

markdown/types.arraytype.md

@@ -22,17 +22,17 @@ export declare class ArrayType<ElementType extends BaseTypeImpl<Element>, Elemen
 
 ## Properties
 
-| Property                                            | Modifiers             | Type                                          | Description |
-| --------------------------------------------------- | --------------------- | --------------------------------------------- | ----------- |
-| [basicType](./types.arraytype.basictype.md)         | <code>readonly</code> | 'array'                                       |             |
-| [elementType](./types.arraytype.elementtype.md)     | <code>readonly</code> | ElementType                                   |             |
-| [isDefaultName](./types.arraytype.isdefaultname.md) | <code>readonly</code> | boolean                                       |             |
-| [name](./types.arraytype.name.md)                   | <code>readonly</code> | string                                        |             |
-| [typeConfig](./types.arraytype.typeconfig.md)       | <code>readonly</code> | [ArrayTypeConfig](./types.arraytypeconfig.md) |             |
+| Property                                            | Modifiers             | Type                                          | Description                                                                 |
+| --------------------------------------------------- | --------------------- | --------------------------------------------- | --------------------------------------------------------------------------- |
+| [basicType](./types.arraytype.basictype.md)         | <code>readonly</code> | 'array'                                       | The kind of values this type validates.                                     |
+| [elementType](./types.arraytype.elementtype.md)     | <code>readonly</code> | ElementType                                   |                                                                             |
+| [isDefaultName](./types.arraytype.isdefaultname.md) | <code>readonly</code> | boolean                                       |                                                                             |
+| [name](./types.arraytype.name.md)                   | <code>readonly</code> | string                                        | The name of the Type.                                                       |
+| [typeConfig](./types.arraytype.typeconfig.md)       | <code>readonly</code> | [ArrayTypeConfig](./types.arraytypeconfig.md) | Extra information that is made available by this Type for runtime analysis. |
 
 ## Methods
 
-| Method                                                              | Modifiers              | Description |
-| ------------------------------------------------------------------- | ---------------------- | ----------- |
-| [accept(visitor)](./types.arraytype.accept.md)                      |                        |             |
-| [typeValidator(input, options)](./types.arraytype.typevalidator.md) | <code>protected</code> |             |
+| Method                                                              | Modifiers              | Description                         |
+| ------------------------------------------------------------------- | ---------------------- | ----------------------------------- |
+| [accept(visitor)](./types.arraytype.accept.md)                      |                        | Accept a visitor (visitor pattern). |
+| [typeValidator(input, options)](./types.arraytype.typevalidator.md) | <code>protected</code> | The actual validation-logic.        |

markdown/types.arraytype.name.md

@@ -4,6 +4,8 @@
 
 ## ArrayType.name property
 
+The name of the Type.
+
 **Signature:**
 
 ```typescript

markdown/types.arraytype.typeconfig.md

@@ -4,6 +4,8 @@
 
 ## ArrayType.typeConfig property
 
+Extra information that is made available by this Type for runtime analysis.
+
 **Signature:**
 
 ```typescript

markdown/types.arraytype.typevalidator.md

@@ -4,6 +4,8 @@
 
 ## ArrayType.typeValidator() method
 
+The actual validation-logic.
+
 **Signature:**
 
 ```typescript
@@ -12,10 +14,10 @@ protected typeValidator(input: unknown, options: ValidationOptions): Result<Resu
 
 ## Parameters
 
-| Parameter | Type                                              | Description |
-| --------- | ------------------------------------------------- | ----------- |
-| input     | unknown                                           |             |
-| options   | [ValidationOptions](./types.validationoptions.md) |             |
+| Parameter | Type                                              | Description                     |
+| --------- | ------------------------------------------------- | ------------------------------- |
+| input     | unknown                                           | the input value to be validated |
+| options   | [ValidationOptions](./types.validationoptions.md) | the current validation context  |
 
 **Returns:**
 

markdown/types.interfacetype._constructor_.md

@@ -9,7 +9,8 @@ Constructs a new instance of the `InterfaceType` class
 **Signature:**
 
 ```typescript
-constructor(props: Props, options: InterfaceTypeOptions);
+constructor(
+    props: Props, options: InterfaceTypeOptions);
 ```
 
 ## Parameters

markdown/types.interfacetype.accept.md

@@ -4,6 +4,8 @@
 
 ## InterfaceType.accept() method
 
+Accept a visitor (visitor pattern).
+
 **Signature:**
 
 ```typescript
@@ -12,10 +14,14 @@ accept<R>(visitor: Visitor<R>): R;
 
 ## Parameters
 
-| Parameter | Type                                           | Description |
-| --------- | ---------------------------------------------- | ----------- |
-| visitor   | [Visitor](./types.visitor.md)<!-- -->&lt;R&gt; |             |
+| Parameter | Type                                           | Description           |
+| --------- | ---------------------------------------------- | --------------------- |
+| visitor   | [Visitor](./types.visitor.md)<!-- -->&lt;R&gt; | the visitor to accept |
 
 **Returns:**
 
 R
+
+## Remarks
+
+Note that, while it can be used to traverse a tree, this is not part of this pattern. The visitor that visits a particular type can decide to visit children of that type (or not). See `./testutils.ts` for an example.

markdown/types.interfacetype.basictype.md

@@ -4,8 +4,14 @@
 
 ## InterfaceType.basicType property
 
+The kind of values this type validates.
+
 **Signature:**
 
 ```typescript
 readonly basicType: 'object';
 ```
+
+## Remarks
+
+See [BasicType](./types.basictype.md) for more info about the rationale behind the basic type.