umberto 2.2.0 → 2.3.1

package/src/data-converter/converters/typedoc/functionparser.js

@@ -0,0 +1,61 @@
+/**
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const AbstractParser = require( './abstractparser' );
+
+module.exports = class FunctionParser extends AbstractParser {
+	/**
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {Boolean}
+	 */
+	canParse( item ) {
+		return item.kindString === 'Function';
+	}
+
+	/**
+	 * @param {TypedocReflection<'Function'>} item
+	 * @param {String} parentName
+	 * @returns {Array.<Object>}
+	 */
+	parse( item, parentName ) {
+		return item.signatures.map( ( signature, index ) => {
+			const doclet = {
+				// Needed for post-processing once all project reflections are converted.
+				_signature: signature,
+
+				name: item.name,
+				memberof: parentName,
+				longname: this.getLongName( item, parentName ),
+
+				scope: this.getScope( signature ),
+				access: this.getVisibility( signature ),
+				kind: this.getKind( item ),
+				extraId: this.getExtraId( item ),
+				description: this.getComment( signature ),
+				file: this.getFile( item, index ),
+				skipSource: this.shouldSkipSource( signature ),
+				deprecated: this.isDeprecated( signature ),
+				see: this.getRelated( signature, parentName ),
+
+				isOverloaded: item.signatures.length > 1,
+				label: this._getLabelName( signature ),
+
+				// These properties will be filled in the post-processing phase.
+				returns: null,
+				params: null,
+				typeParameters: null
+			};
+
+			// Add a label as suffix for overloaded members.
+			if ( doclet.label ) {
+				doclet.extraId += ':' + doclet.label;
+			}
+
+			return doclet;
+		} );
+	}
+};

package/src/data-converter/converters/typedoc/interfaceparser.js

@@ -0,0 +1,46 @@
+/**
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const AbstractParser = require( './abstractparser' );
+
+module.exports = class InterfaceParser extends AbstractParser {
+	/**
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {Boolean}
+	 */
+	canParse( item ) {
+		return item.kindString === 'Interface';
+	}
+
+	/**
+	 * @param {TypedocReflection<'Interface'>} item
+	 * @param {String} parentName
+	 * @returns {Object}
+	 */
+	parse( item, parentName ) {
+		return {
+			// Needed for post-processing once all project reflections are converted.
+			_signature: item,
+
+			name: item.name,
+			memberof: parentName,
+			longname: this.getLongName( item, parentName ),
+
+			scope: this.getScope( item ),
+			kind: this.getKind( item ),
+			extraId: this.getExtraId( item ),
+			description: this.getComment( item ),
+			file: this.getFile( item ),
+			skipSource: this.shouldSkipSource( item ),
+			deprecated: this.isDeprecated( item ),
+
+			typeParameters: null,
+			augmentsNested: null,
+			descendants: null
+		};
+	}
+};

package/src/data-converter/converters/typedoc/methodparser.js

@@ -0,0 +1,63 @@
+/**
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const AbstractParser = require( './abstractparser' );
+
+module.exports = class MethodParser extends AbstractParser {
+	/**
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {Boolean}
+	 */
+	canParse( item ) {
+		return item.kindString === 'Method';
+	}
+
+	/**
+	 * @param {TypedocReflection<ConstructorOrMethod>} item
+	 * @param {String} parentName
+	 * @returns {Array.<Object>}
+	 */
+	parse( item, parentName ) {
+		return item.signatures.map( ( signature, index ) => {
+			const doclet = {
+				// Needed for post-processing once all project reflections are converted.
+				_signature: signature,
+
+				name: item.name,
+				memberof: parentName,
+				longname: this.getLongName( item, parentName ),
+
+				scope: this.getScope( item ),
+				kind: this.getKind( item ),
+				access: this.getVisibility( item ),
+				extraId: this.getExtraId( item ),
+				fires: this.getFiredEvents( signature, parentName ),
+				description: this.getComment( signature ),
+				file: this.getFile( item, index ),
+				skipSource: this.shouldSkipSource( signature ),
+				deprecated: this.isDeprecated( signature ),
+				inherited: !!signature.inheritedFrom,
+				see: this.getRelated( signature, parentName ),
+
+				isOverloaded: item.signatures.length > 1,
+				label: this._getLabelName( signature ),
+
+				// These properties will be filled in the post-processing phase.
+				returns: null,
+				params: null,
+				typeParameters: null
+			};
+
+			// Add a label as suffix for overloaded members.
+			if ( doclet.label ) {
+				doclet.extraId += ':' + doclet.label;
+			}
+
+			return doclet;
+		} );
+	}
+};

package/src/data-converter/converters/typedoc/moduleparser.js

@@ -0,0 +1,31 @@
+/**
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const AbstractParser = require( './abstractparser' );
+
+module.exports = class ModuleParser extends AbstractParser {
+	/**
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {Boolean}
+	 */
+	canParse( item ) {
+		return item.kindString === 'Module';
+	}
+
+	/**
+	 * @param {TypedocReflection<'Module'>} item
+	 * @returns {Object}
+	 */
+	parse( item ) {
+		return {
+			name: item.name,
+			longname: this.getLongName( item ),
+			kind: this.getKind( item ),
+			extraId: this.getExtraId( item )
+		};
+	}
+};

package/src/data-converter/converters/typedoc/propertyparser.js

@@ -0,0 +1,74 @@
+/**
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const AbstractParser = require( './abstractparser' );
+
+module.exports = class PropertyParser extends AbstractParser {
+	/**
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {Boolean}
+	 */
+	canParse( item ) {
+		return item.kindString === 'Property' && item.name !== 'constructor';
+	}
+
+	/**
+	 * @param {TypedocReflection<'Property'>} item
+	 * @param {String} parentName
+	 * @returns {Object}
+	 */
+	parse( item, parentName ) {
+		// By default, a comment that is associated in the source code with the property, is bound to the item itself, as anyone would
+		// expect. TypeDoc works differently for a callable property, for which the comment is moved down to the property signature.
+		// Hence, we must extract it back from the property signature to be able to display it correctly in the API docs.
+		const description = isCallableProperty( item ) ?
+			this.getComment( item.type.declaration.signatures[ 0 ] ) :
+			this.getComment( item );
+
+		return {
+			// Needed for post-processing once all project reflections are converted.
+			_signature: [ item, {} ],
+
+			name: item.name,
+			memberof: parentName,
+			longname: this.getLongName( item, parentName ),
+
+			scope: this.getScope( item ),
+			readonly: this.isReadonly( item ),
+			observable: this.isObservable( item ),
+			access: this.getVisibility( item ),
+			optional: this.isOptional( item ),
+			kind: this.getKind( item ),
+			extraId: this.getExtraId( item ),
+			description,
+			file: this.getFile( item ),
+			skipSource: this.shouldSkipSource( item ),
+			deprecated: this.isDeprecated( item ),
+			inherited: !!item.inheritedFrom,
+			see: this.getRelated( item, parentName ),
+
+			// This property will be filled in the post-processing phase.
+			type: null
+		};
+	}
+};
+
+/**
+ * @param {TypedocReflectionType} item
+ * @returns {Boolean}
+ */
+function isCallableProperty( item ) {
+	if ( item.type.type !== 'reflection' ) {
+		return false;
+	}
+
+	if ( !Array.isArray( item.type.declaration.signatures ) ) {
+		return false;
+	}
+
+	return true;
+}

package/src/data-converter/converters/typedoc/typedoc.ts

@@ -0,0 +1,299 @@
+/**
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+// This file contains several types and definitions used in the Typedoc converter mechanism.
+// It is not loaded anywhere in Umberto, and should not cause any errors.
+
+/**
+ * @typeParameter V Kind string.
+ */
+export type TypedocReflectionMeta<V extends string> = {
+
+	/**
+	 * A name of a parser that should process given structure.
+	 */
+	kindString: V;
+
+	/**
+	 * An internal (Typedoc) kind identifier.
+	 */
+	kind: number;
+
+	/**
+	 * An identifier used to map reference reflections.
+	 */
+	id: number;
+
+	/**
+	 * A name of a member.
+	 */
+	name: string;
+
+	flags: Record<
+		'isReadonly' | 'isPrivate' | 'isProtected' | 'isPublic' | 'isStatic' | 'isOptional' | 'isRest' | 'isExternal',
+		true | undefined
+	>;
+
+	comment?: {
+
+		/**
+		 * A description of the code. It contains all text found before processing annotations.
+		 */
+		summary: Array<TypedocCommentItem>;
+
+		/**
+		 * Annotations that require additional description, e.g. `@param`.
+		 */
+		blockTags: Array<{
+			tag: `@${ string }`;
+			name: string;
+			content: Array<TypedocCommentItem>;
+		}>;
+
+		/**
+		 * Annotation without descriptions, e.g. `@internal`.
+		 */
+		modifierTags: Array<`@${ string }`>;
+	};
+};
+
+/**
+ * @typeParam T A name of a parser that should process given structure.
+ */
+export type TypedocReflection<T extends TypedocParsers> = TypedocReflectionMeta<T> & {
+
+	/**
+	 * An array of reflections children if the given structure can be a parent. Otherwise, `undefined`.
+	 */
+	children: ChildrenMap[T] extends null ? undefined : Array<ChildrenMap[T]>;
+
+	/**
+	 * An array of parent classes or interfaces that given structure extends.
+	 */
+	extendedTypes: T extends ClassOrInterface ? Array<TypedocReflectionMeta<TypedocParsers>> : undefined;
+
+	/**
+	 * An array of interfaces that given class implements.
+	 */
+	implementedTypes: T extends 'Class' ? Array<TypedocReflectionMeta<TypedocParsers>> : undefined;
+
+	/**
+	 * Type parameters for an interface or a class.
+	 *
+	 * Also, due to lack of knowledge how to create parameters for a custom structure, we keep event arguments here.
+	 */
+	typeParameters: T extends ClassOrInterface | 'Event' ? Array<TypedocReflectionTypeParameter> : undefined;
+
+	/**
+	 * Type parameters for a constant or a callable expression.
+	 */
+	typeParameter: T extends 'Variable' | 'Method' | 'Function' ? Array<TypedocReflectionTypeParameter> : undefined;
+
+	/**
+	 * For inherited properties, the property contains a parent reflection.
+	 */
+	inheritedFrom: T extends 'Method' | 'Function' ? Record<string, any> : undefined;
+
+	/**
+	 * The `signatures` property exists only for callable doclets.
+	 */
+	signatures: T extends ConstructorOrMethod | 'Function' ? Array<TypedocCallSignature> : undefined;
+
+	/**
+	 * A value defined by an exported constant (`export const ...`).
+	 */
+	defaultValue: T extends 'Variable' ? TypedocReflectionType : undefined;
+
+	/**
+	 * The `setSignature` and `getSignature` exist only when processing a getter or/and setter.
+	 *
+	 * However, the getter does not allow setting a value. The `set*` property does not exist in such a case.
+	 * The same applies to setters and their `get*` properties.
+	 */
+	setSignature?: T extends 'Accessor' ? TypedocCallSignature : undefined;
+	getSignature?: T extends 'Accessor' ? TypedocCallSignature : undefined;
+
+	/**
+	 * An array of sources that defines given structure.
+	 */
+	sources?: Array<TypedocSource>;
+	originalName?: string;
+};
+
+export type TypedocReflectionType = TypedocReflectionMeta<'Parameter'> & {
+	type: TypedocTypeDetails;
+	elementType?: TypedocTypeDetails;
+	declaration?: {
+		signatures?: Array<TypedocCallSignature>;
+		children?: Array<TypedocReflection<TypedocParsers>>;
+	};
+	types?: Array<TypedocReflectionType>;
+	defaultValue?: string;
+};
+
+export type TypedocReflectionTypeParameter = TypedocReflectionMeta<'Type parameter'> & TypedocTypeDetails & {
+	default?: TypedocTypeDetails;
+	type?: TypedocReflectionType;
+};
+
+export type TypedocCallSignature = TypedocReflectionMeta<'Call signature'> & {
+	type: TypedocReflectionType;
+	parameters?: Array<TypedocReflectionType>;
+	inheritedFrom?: Record<string, any>;
+};
+
+export type TypedocTypeDetails = string | LiteralOrIntrinsic | Reference | TypeOperator |
+	{
+		type: 'union';
+		types: Array<TypedocReflectionType>;
+	} |
+	{
+		type: 'array';
+		elementType: TypedocTypeDetails;
+	} |
+	{
+		type: 'indexedAccess';
+		objectType: TypedocTypeDetails;
+		indexType: TypedocTypeDetails;
+	} |
+	{
+		type: 'reflection';
+		declaration: {
+			signatures?: Array<TypedocCallSignature>;
+		};
+	} |
+	{
+		type: 'tuple';
+		elements: Array<TypedocTypeDetails>;
+	} |
+	{
+		type: 'named-tuple-member';
+		element: TypedocTypeDetails;
+	} |
+	{
+		type: 'intersection';
+		types: Array<TypedocReflectionType>;
+	} |
+	{
+		type: 'query';
+		queryType: {
+			name: string;
+		};
+	} |
+	{
+		type: 'mapped';
+		parameter: string;
+		parameterType?: TypeOperator | string;
+		templateType: LiteralOrIntrinsic;
+		optionalModifier?: string;
+	} |
+	{
+		type: 'conditional';
+		checkType: Reference;
+		extendsType: TypedocTypeDetails;
+		trueType: TypedocTypeDetails;
+		falseType: TypedocTypeDetails;
+	} |
+	{
+		type: 'template-literal';
+		tail: Array<{
+			type: TypedocTypeDetails;
+			suffix: string;
+		}>;
+		head: string;
+	} |
+	{
+		type: 'predicate';
+		targetType: TypedocTypeDetails;
+	};
+
+export type TypedocCommentItem = {
+	kind: 'text' | 'code' | 'inline-tag';
+	text: string;
+
+	/**
+	 * Available when `kind === 'inline-tag'`.
+	 */
+	tag?: string;
+
+	/**
+	 * Available if `tag === '@link'` and it points to an existing reflection.
+	 */
+	target?: number;
+};
+
+/**
+ * Available parsers for processing reflections.
+ */
+export type TypedocParsers = keyof ChildrenMap;
+
+/**
+ * An alias for callable properties from a class or an interface.
+ */
+export type ConstructorOrMethod = 'Constructor' | 'Method';
+
+/**
+ * An alias for types that contains children.
+ */
+type ClassOrInterface = 'Class' | 'Interface';
+
+/**
+ * A map containing the possible types of children for a given parent type.
+ */
+type ChildrenMap = {
+	// Root.
+	Module: TypedocReflection<ClassOrInterface | 'Function' | 'Type alias' | 'Error' | 'Variable'>;
+
+	// Module children.
+	Class: TypedocReflection<ConstructorOrMethod | 'Event' | 'Accessor' | 'Property'>;
+	Interface: TypedocReflection<ConstructorOrMethod | 'Event' | 'Accessor' | 'Property'>;
+	Function: null;
+	'Type alias': null;
+	Error: null;
+	Variable: null;
+
+	// Class/interface children.
+	Constructor: null;
+	Method: null;
+	Property: null;
+	Accessor: null;
+	Event: null;
+
+	// A special "parser" that points to an existing doclet that most probably has been already converted.
+	Reference: null;
+
+	// To detect if a specified argument is a class instance or a function.
+	'Constructor signature': null;
+};
+
+type TypedocSource = {
+	fileName: string;
+	line: number;
+	character: number;
+	url: string;
+};
+
+type Reference = {
+	type: 'reference';
+	name: string;
+	id?: number;
+	typeArguments?: Array<TypedocReflectionTypeParameter>;
+};
+
+type TypeOperator = {
+	type: 'typeOperator';
+	operator: string;
+	target: Reference;
+};
+
+type LiteralOrIntrinsic =
+	{
+		type: 'literal';
+		value: string | number | boolean | null;
+	} |
+	{
+		type: 'intrinsic';
+		name: string;
+	};