umberto 2.2.0 → 2.3.1

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

@@ -0,0 +1,372 @@
+/**
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const TypedocConverter = require( './typedocconverter' );
+
+/**
+ * An abstract parser class providing basic utils for converting Typedoc reflection to JSDoc doclet.
+ */
+module.exports = class AbstractParser {
+	/**
+	 * @abstract
+	 * @method canParse
+	 * @param {TypedocReflection<TypedocParsers>} item
+	 * @returns {Boolean}
+	 */
+
+	/**
+	 * @abstract
+	 * @method parse
+	 * @param {TypedocReflection<TypedocParsers>} item
+	 * @param {String|null} [parentName=null]
+	 * @returns {Object}
+	 */
+
+	/**
+	 * Coverts the item's comment from Markdown to HTML.
+	 *
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {String}
+	 */
+	getComment( item ) {
+		if ( item.comment && Array.isArray( item.comment.summary ) ) {
+			return TypedocConverter.convertComment( item.comment.summary );
+		}
+
+		return '';
+	}
+
+	/**
+	 * @param {TypedocReflectionMeta} item
+	 * @param {String|null} [parentName=null]
+	 * @returns {String}
+	 */
+	getLongName( item, parentName = null ) {
+		let separator;
+
+		switch ( item.kindString ) {
+			case 'Module':
+				separator = ':';
+				parentName = 'module';
+				break;
+
+			case 'Class':
+			case 'Function':
+			case 'Interface':
+			case 'Type alias':
+				separator = '~';
+				break;
+
+			case 'Event':
+				separator = '#event:';
+				break;
+
+			default:
+				separator = this.getScope( item ) === 'static' ? '.' : '#';
+				break;
+		}
+
+		return `${ parentName }${ separator }${ item.name }`;
+	}
+
+	/**
+	 * Returns the access type for the item.
+	 *
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {'public'|'internal'|'protected'|'private'}
+	 */
+	getVisibility( item ) {
+		const flags = item.flags || {};
+
+		if ( this.isInternal( item ) ) {
+			return 'internal';
+		}
+
+		if ( flags.isProtected ) {
+			return 'protected';
+		}
+
+		if ( flags.isPrivate ) {
+			return 'private';
+		}
+
+		return 'public';
+	}
+
+	/**
+	 * Returns the item's kind.
+	 *
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {String}
+	 */
+	getKind( item ) {
+		switch ( item.kindString ) {
+			case 'Module':
+				return 'module';
+
+			case 'Class':
+				return 'class';
+
+			case 'Function':
+			case 'Method':
+			case 'Constructor':
+				return 'function';
+
+			case 'Interface':
+				return 'interface';
+
+			case 'Accessor':
+			case 'Property':
+				return 'member';
+
+			case 'Variable':
+				return 'constant';
+
+			case 'Type alias':
+				return 'typedef';
+
+			case 'Event':
+				return 'event';
+
+			case 'Error':
+				return 'error';
+		}
+	}
+
+	/**
+	 * Returns the item's scope.
+	 *
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {'instance'|'static'}
+	 */
+	getScope( item ) {
+		const flags = item.flags || {};
+
+		if ( flags.isStatic ) {
+			return 'static';
+		}
+
+		return 'instance';
+	}
+
+	/**
+	 * Returns the `extraId` combined from the item's scope, kind, name and optional variation.
+	 *
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {String}
+	 */
+	getExtraId( item ) {
+		const staticModifier = this.getScope( item ) === 'static' ? 'static-' : '';
+
+		return staticModifier + this.getKind( item ) + '-' + item.name;
+	}
+
+	/**
+	 * Returns the long names of the events that are fired from the signature.
+	 *
+	 * @param {TypedocReflectionMeta} signature
+	 * @param {String} parentName
+	 * @returns {Array.<String>|null}
+	 */
+	getFiredEvents( signature, parentName ) {
+		if ( !signature.comment || !signature.comment.blockTags ) {
+			return null;
+		}
+
+		return signature.comment.blockTags
+			.filter( blockTag => blockTag.tag === '@fires' )
+			.map( blockTag => {
+				const content = blockTag.content[ 0 ].text;
+
+				if ( content.startsWith( 'module:' ) ) {
+					return content;
+				}
+
+				return `${ parentName }#event:${ content }`;
+			} );
+	}
+
+	/**
+	 * Returns the URL to GitHub with selected line, where the given doclet is defined.
+	 * The URL includes a commit hash which was used to build the API docs.
+	 *
+	 * @param {TypedocReflection<TypedocParsers>} item
+	 * @param {Number} sourceIndex
+	 * @returns {Object|null}
+	 */
+	getFile( item, sourceIndex = 0 ) {
+		if ( !item.sources ) {
+			return null;
+		}
+
+		const { url } = item.sources[ sourceIndex ];
+
+		if ( !url ) {
+			return null;
+		}
+
+		return { url };
+	}
+
+	/**
+	 * Returns links from the "@see" tags.
+	 *
+	 * @param {TypedocReflectionMeta} item
+	 * @param {String|null} [parentName=null]
+	 * @returns {Array.<String>}
+	 */
+	getRelated( item, parentName ) {
+		if ( !item.comment || !item.comment.blockTags ) {
+			return null;
+		}
+
+		return item.comment.blockTags
+			.filter( blockTag => blockTag.tag === '@see' )
+			.flatMap( blockTag => {
+				const items = blockTag.content
+					.map( ( { text } ) => text.trim() )
+					// To remove list markers.
+					.filter( text => text.length > 1 );
+
+				if ( !parentName ) {
+					return items;
+				}
+
+				return items.map( text => {
+					// A full reference to a module.
+					if ( text.startsWith( 'module:' ) ) {
+						return text;
+					}
+
+					// A short reference to an existing item in the `parentName` module.
+					if ( text.startsWith( '~' ) ) {
+						const [ moduleName ] = parentName.split( '~' );
+
+						return moduleName + text;
+					}
+
+					return parentName + text;
+				} );
+			} );
+	}
+
+	/**
+	 * Checks if the item is readonly.
+	 *
+	 * The readonly state can be marked either by a TypeScript `readonly` keyword, or by the `@readonly` JSDoc keyword.
+	 *
+	 * @param {TypedocReflection} item
+	 * @returns {Boolean}
+	 */
+	isReadonly( item ) {
+		if ( item.flags && item.flags.isReadonly ) {
+			return true;
+		}
+
+		return false;
+	}
+
+	/**
+	 * Checks if the item is observable.
+	 *
+	 * The observable state can be marked by the `@observable` JSDoc keyword.
+	 *
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {Boolean}
+	 */
+	isObservable( item ) {
+		if ( item.comment && item.comment.blockTags ) {
+			return item.comment.blockTags.some( tag => tag.tag === '@observable' );
+		}
+
+		return false;
+	}
+
+	/**
+	 * Checks if the item is marked as an optional.
+	 *
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {Boolean}
+	 */
+	isOptional( item ) {
+		if ( item.flags && item.flags.isOptional ) {
+			return true;
+		}
+
+		return false;
+	}
+
+	/**
+	 * Checks if the member is marked as `internal` one.
+	 *
+	 * The `internal` state means the same as `protected`, but with one exception: the `internal` member can be used from outside the class
+	 * in which it is defined (or its derivatives), as opposed to the `protected` state.
+	 *
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {Boolean}
+	 */
+	isInternal( item ) {
+		if ( item.comment && item.comment.modifierTags ) {
+			return item.comment.modifierTags.some( tag => tag === '@internal' );
+		}
+
+		return false;
+	}
+
+	/**
+	 * Checks if the member is marked by the `@deprecated` JSDoc tag.
+	 *
+	 * @param {TypedocReflectionMeta>} item
+	 * @returns {Boolean}
+	 */
+	isDeprecated( item ) {
+		if ( item.comment && item.comment.blockTags ) {
+			return item.comment.blockTags.some( tag => tag.tag === '@deprecated' );
+		}
+
+		return false;
+	}
+
+	/**
+	 * Checks if the member contains the `@skipSource` annotation.
+	 *
+	 * Note: The `skipSource` flag can be set to `true` even if the member does not contain the annotation.
+	 * It happens when the member has not specified `file` property. In such a case, Umberto does not know
+	 * where to point to a source and decides to skip generating the "See source" button.
+	 *
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {Boolean}
+	 */
+	shouldSkipSource( item ) {
+		if ( item.comment && item.comment.modifierTags ) {
+			return item.comment.modifierTags.some( tag => tag === '@skipSource' );
+		}
+
+		return false;
+	}
+
+	/**
+	 * Returns a name specified in the `@label` annotation.
+	 *
+	 * @protected
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {String}
+	 */
+	_getLabelName( item ) {
+		if ( item.comment && item.comment.blockTags ) {
+			const labelComment = item.comment.blockTags.find( tag => tag.tag === '@label' );
+
+			if ( !labelComment ) {
+				return '';
+			}
+
+			return labelComment.content[ 0 ].text;
+		}
+
+		return '';
+	}
+};

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

@@ -0,0 +1,64 @@
+/**
+ * @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 AccessorParser extends AbstractParser {
+	/**
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {Boolean}
+	 */
+	canParse( item ) {
+		return item.kindString === 'Accessor';
+	}
+
+	/**
+	 * Checks if the accessor is readonly.
+	 *
+	 * @override
+	 * @param {TypedocReflection} item
+	 * @returns {Boolean}
+	 */
+	isReadonly( item ) {
+		return !item.setSignature;
+	}
+
+	/**
+	 * @param {TypedocReflection<'Accessor'>} item
+	 * @param {String} parentName
+	 * @returns {Object}
+	 */
+	parse( item, parentName ) {
+		// A getter and setter can't be overloaded, so their first signature (if exists) is the only one.
+		// Starting from `typedoc@0.23`, these properties are no longer an array.
+		const { getSignature, setSignature } = item;
+
+		return {
+			// Needed for post-processing once all project reflections are converted.
+			_signature: [ getSignature || {}, setSignature || {} ],
+
+			name: item.name,
+			memberof: parentName,
+			longname: this.getLongName( item, parentName ),
+
+			scope: this.getScope( item ),
+			readonly: this.isReadonly( item ),
+			access: this.getVisibility( item ),
+			kind: this.getKind( item ),
+			extraId: this.getExtraId( item ),
+			description: this.getComment( getSignature || setSignature ),
+			file: this.getFile( item ),
+			skipSource: this.shouldSkipSource( getSignature || setSignature ),
+			deprecated: this.isDeprecated( getSignature || setSignature ),
+			inherited: !!item.inheritedFrom,
+
+			// These properties will be filled in the post-processing phase.
+			type: null,
+			params: null
+		};
+	}
+};

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

@@ -0,0 +1,49 @@
+/**
+ * @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 ClassParser extends AbstractParser {
+	/**
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {Boolean}
+	 */
+	canParse( item ) {
+		return item.kindString === 'Class';
+	}
+
+	/**
+	 * @param {TypedocReflection<'Class'>} 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 ),
+			access: this.getVisibility( 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 ),
+
+			// Properties specified below will be mapped to module names once the entire project is transformed.
+			typeParameters: null,
+			augmentsNested: null,
+			implementsNested: null,
+			descendants: null
+		};
+	}
+};

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

@@ -0,0 +1,45 @@
+/**
+ * @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 ConstantParser extends AbstractParser {
+	/**
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {Boolean}
+	 */
+	canParse( item ) {
+		return item.kindString === 'Variable';
+	}
+
+	/**
+	 * @param {TypedocReflection<'Variable'>} 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: 'inner',
+			kind: this.getKind( item ),
+			extraId: `constant-${ item.name }`,
+			file: this.getFile( item ),
+			skipSource: this.shouldSkipSource( item ),
+			description: this.getComment( item ),
+			deprecated: this.isDeprecated( item ),
+
+			// This property will be filled in the post-processing phase.
+			type: null
+		};
+	}
+};

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

@@ -0,0 +1,34 @@
+/**
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const MethodParser = require( './methodparser' );
+
+module.exports = class ConstructorParser extends MethodParser {
+	/**
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {Boolean}
+	 */
+	canParse( item ) {
+		return item.kindString === 'Constructor';
+	}
+
+	/**
+	 * @param {TypedocReflection<'Constructor'>} item
+	 * @param {String} parentName
+	 * @returns {Array.<Object>}
+	 */
+	parse( item, parentName ) {
+		const results = super.parse( item, parentName );
+
+		for ( const item of results ) {
+			// Constructors cannot return any value.
+			delete item.returns;
+		}
+
+		return results;
+	}
+};

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

@@ -0,0 +1,44 @@
+/**
+ * @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 ErrorParser extends AbstractParser {
+	/**
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {Boolean}
+	 */
+	canParse( item ) {
+		return item.kindString === 'Error';
+	}
+
+	/**
+	 * @param {TypedocReflection<'Error'>} item
+	 * @returns {Object}
+	 */
+	parse( item ) {
+		return {
+			_signature: [
+				{},
+				// As errors are our custom implementation, TypeDoc does not allow creating `parameters` property for them. Error parameters
+				// are passed in `typeParameters` property. To process the error parameters properly, we manually map `typeParameters` into
+				// `parameters` property.
+				{ parameters: item.typeParameters }
+			],
+
+			kind: this.getKind( item ),
+			scope: 'inner',
+			name: item.name,
+			longname: `module:errors/${ item.name }`,
+			extraId: this.getExtraId( item ),
+			description: this.getComment( item ),
+
+			// This property will be filled in the post-processing phase.
+			params: null
+		};
+	}
+};

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

@@ -0,0 +1,57 @@
+/**
+ * @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 EventParser extends AbstractParser {
+	/**
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {Boolean}
+	 */
+	canParse( item ) {
+		return item.kindString === 'Event';
+	}
+
+	/**
+	 * @param {TypedocReflection<'Event'>} item
+	 * @param {String} parentName
+	 * @returns {Object}
+	 */
+	parse( item, parentName ) {
+		// TypeDoc adds the "event:" prefix to the event name to make sure the name is unique in the scope of its parent.
+		// Here, in the parser, we do not need it anymore.
+		item.name = item.name.replace( 'event:', '' );
+
+		return {
+			// Needed for post-processing once all project reflections are converted.
+			_signature: [
+				{},
+				// As events are our custom implementation, TypeDoc does not allow creating `parameters` property for them. Event parameters
+				// are passed in `typeParameters` property. To process the event parameters properly, we manually map `typeParameters` into
+				// `parameters` property.
+				{ parameters: item.typeParameters }
+			],
+
+			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 ),
+			inherited: !!item.inheritedFrom,
+			see: this.getRelated( item, parentName ),
+
+			// These properties will be filled in the post-processing phase.
+			params: null
+		};
+	}
+};