umberto 2.2.0 → 2.3.0

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

@@ -0,0 +1,71 @@
+/**
+ * @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 TypeParser extends AbstractParser {
+	/**
+	 * @param {TypedocReflectionMeta} item
+	 * @returns {Boolean}
+	 */
+	canParse( item ) {
+		return item.kindString === 'Type alias';
+	}
+
+	/**
+	 * @param {TypedocReflection<'Type alias'>} item
+	 * @param {String} parentName
+	 * @returns {Object}
+	 */
+	parse( item, parentName ) {
+		const result = {
+			name: item.name,
+			memberof: parentName,
+			longname: this.getLongName( item, parentName ),
+
+			scope: 'inner',
+			kind: this.getKind( item ),
+			extraId: this.getExtraId( item ),
+			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.
+			typeParameters: null
+		};
+
+		// There are two distinct type definitions that are rendered in own way by Umberto: function type and object type.
+		// For function type, its params and return type is displayed. For object, all its properties are shown.
+		const isFunctionType = item.type.declaration && item.type.declaration.signatures;
+
+		if ( isFunctionType ) {
+			// Needed for post-processing once all project reflections are converted.
+			result._signature = item.type.declaration.signatures[ 0 ];
+
+			result.description = this.getComment( result._signature );
+			result.type = {
+				names: [
+					'function'
+				]
+			};
+
+			// These properties will be filled in the post-processing phase.
+			result.returns = null;
+			result.params = null;
+		} else {
+			// Needed for post-processing once all project reflections are converted.
+			result._signature = item;
+
+			// These properties will be filled in the post-processing phase.
+			result.properties = null;
+			result.type = null;
+		}
+
+		return result;
+	}
+};

package/src/data-converter/converters/typedoc2umberto.js

@@ -0,0 +1,52 @@
+/**
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const TypedocConverter = require( './typedoc/typedocconverter' );
+const ModuleParser = require( './typedoc/moduleparser' );
+const ClassParser = require( './typedoc/classparser' );
+const AccessorParser = require( './typedoc/accessorparser' );
+const InterfaceParser = require( './typedoc/interfaceparser' );
+const ConstantParser = require( './typedoc/constantparser' );
+const TypeParser = require( './typedoc/typeparser' );
+const FunctionParser = require( './typedoc/functionparser' );
+const PropertyParser = require( './typedoc/propertyparser' );
+const MethodParser = require( './typedoc/methodparser' );
+const ConstructorParser = require( './typedoc/constructorparser' );
+const ErrorParser = require( './typedoc/errorparser' );
+const EventParser = require( './typedoc/eventparser' );
+
+module.exports = data => {
+	const projectReflection = JSON.parse( data );
+
+	if ( !projectReflection.children ) {
+		console.warn( 'No doclets found in passed data.' );
+
+		return [];
+	}
+
+	const typedoc = new TypedocConverter( [
+		// Top level. All things belong to a module.
+		ModuleParser,
+
+		// Module's children.
+		ClassParser,
+		InterfaceParser,
+		FunctionParser,
+		ConstantParser,
+		TypeParser,
+		ErrorParser,
+
+		// Class's and interface's children.
+		ConstructorParser,
+		MethodParser,
+		AccessorParser,
+		PropertyParser,
+		EventParser
+	] );
+
+	return typedoc.convertToJsDoc( projectReflection );
+};

package/src/data-converter/data-collection.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/data-converter/data-provider.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 
@@ -8,10 +8,12 @@
 const DataCollection = require( './data-collection' );
 const jsdoc2umberto = require( './converters/jsdoc2umberto' );
 const jsduck2umberto = require( './converters/jsduck2umberto' );
+const typedoc2umberto = require( './converters/typedoc2umberto' );
 const relationFixer = require( './middlewares/relation-fixer' );
 const converters = new Map( [
 	[ 'jsdoc', jsdoc2umberto ],
-	[ 'jsduck', jsduck2umberto ]
+	[ 'jsduck', jsduck2umberto ],
+	[ 'typedoc', typedoc2umberto ]
 ] );
 
 /**

package/src/data-converter/doclet-collection.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 
@@ -17,6 +17,14 @@ class DocletCollection {
 		this._allData = [];
 	}
 
+	get size() {
+		return this._allData.length;
+	}
+
+	get isEmpty() {
+		return this.size === 0;
+	}
+
 	/**
 	 * Adds doclet to collection. Keeps it sorted by doclet's name.
 	 *
@@ -57,7 +65,11 @@ class DocletCollection {
 	 * @returns {Doclet|null}
 	 */
 	getFirst() {
-		return this._allData.length > 0 ? this._allData[ 0 ] : null;
+		return this.isEmpty ? null : this.getAll()[ 0 ];
+	}
+
+	getByLabel( label ) {
+		return this.getAll().find( doclet => doclet.label === label );
 	}
 }
 

package/src/data-converter/middlewares/relation-fixer.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/helpers/capitalize.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/helpers/copy-file.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/helpers/create-filtering-data-attribs.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/helpers/doc-formats.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 
@@ -7,5 +7,6 @@
 
 module.exports = {
 	jsdoc: 'json',
-	jsduck: 'json'
+	jsduck: 'json',
+	typedoc: 'json'
 };

package/src/helpers/escape-longname.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/helpers/extract-longname.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/helpers/get-api-infobox-tooltip.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/helpers/get-docsearch-config.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/helpers/get-file-patterns-to-process.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/helpers/get-short-module-path.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/helpers/github-url.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/helpers/glob-to-regexp.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/helpers/html-safe.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/helpers/is-non-empty-array.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/helpers/snippets.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/helpers/split-longname.js

@@ -1,26 +1,95 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 
 'use strict';
 
+const { MEMBER_NAME_REGEXP, LONG_NAME_LABEL_REGEXP } = require( '../api-builder/utils/utils' );
+
+/**
+ * @param {String} longname
+ * @returns {LongNameParts}
+ */
 module.exports = longname => {
 	if ( !longname || typeof longname !== 'string' ) {
 		return {};
 	}
 
+	// Processing a literal value. Let's return it without modifications.
+	if ( longname.startsWith( '\'' ) && longname.endsWith( '\'' ) ) {
+		return {
+			isSingle: true,
+			name: longname,
+			longnameBase: '',
+			directoryNames: []
+		};
+	}
+
 	const parts = longname.split( '/' );
-	const nameMatch = /[:{}\-\w$]+$/.exec( longname );
-	const name = nameMatch ? nameMatch[ 0 ].replace( 'module:', '' ) : ''; // last part of the longname
-	const longnameBase = longname.slice( 0, -( name.length + 1 ) );
+	let [ , nameMatch, label ] = MEMBER_NAME_REGEXP.exec( longname ) || [];
+
+	let name = nameMatch ? nameMatch.replace( 'module:', '' ) : ''; // last part of the longname
+	let longnameBase = longname.split( new RegExp( '[#.]' + name ) )[ 0 ];
+
+	// Remove the label part from a member name.
+	name = name.replace( LONG_NAME_LABEL_REGEXP, '' );
+
+	const isStatic = longname[ longnameBase.length ] === '.' || longnameBase.startsWith( '.' ) || longnameBase.endsWith( '.' );
+
+	// `longnameBase` might start or end with a symbol. It depends if it is a full or short link.
+	longnameBase = longnameBase.replace( /^[#~.]|[#~.]$/g, '' );
+
+	// Support for links containing a doclet type.
+	// E.g., `CKEDITOR.feature#property-allowedContent`.
+	if ( name.includes( '-' ) ) {
+		let [ type, description ] = name.split( '-' );
+
+		// JSDuck replaces `$` with `s-`.
+		if ( type === 's' ) {
+			description = `s-${ description }`;
+		}
+
+		// For events, we want to keep the `name` as it is specified.
+		if ( type === 'event' ) {
+			name = type;
+
+			// An event within a namespace.
+			if ( label ) {
+				label = `${ description }:${ label }`;
+			}
+			else {
+				label = description;
+			}
+		}
+		// Otherwise, skip the type. Use the name only.
+		else {
+			name = description;
+		}
+	}
 
 	if ( parts.length === 1 ) {
+		// When processing a string that looks like an assignment expression,
+		// let's return the original string (do not cut it anywhere).
+		// It is useful when processing a generic argument.
+		const isTypeAssignment = longname.split( '=' ).length === 2;
+
+		if ( isTypeAssignment ) {
+			return {
+				isSingle: true,
+				name: longname,
+				longnameBase: '',
+				directoryNames: []
+			};
+		}
+
 		return {
 			isSingle: true,
 			name,
 			longnameBase,
-			directoryNames: []
+			directoryNames: [],
+			label,
+			isStatic
 		};
 	}
 
@@ -36,11 +105,35 @@ module.exports = longname => {
 	const directoryNames = parts;
 
 	return {
-		name, // last part of longname
-		longnameBase, // longname without the last part
+		name,
+		longnameBase,
 		moduleName,
 		className,
 		packageName,
-		directoryNames
+		directoryNames,
+		label,
+		isStatic
 	};
 };
+
+/**
+ * @typedef {Object} LongNameParts
+ *
+ * @property {Array.<String>} [directoryNames]
+ *
+ * @property {Boolean} [isStatic]
+ *
+ * @property {Boolean} [isSingle]
+ *
+ * @property {String} [longnameBase]
+ *
+ * @property {String} [moduleName]
+ *
+ * @property {String} [className]
+ *
+ * @property {String} [packageName]
+ *
+ * @property {String} [name]
+ *
+ * @property {String} [label]
+ */

package/src/hexo/filter/extend-config.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/hexo/filter/project-locals.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/hexo/get-repo-urls.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/hexo/helper/get-page-group.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/hexo/project-globals.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/hexo-manager.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/index.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/sdk-builder/get-sdk-sources.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/sdk-builder/sdk-builder.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/tasks/build-api-docs.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 
@@ -25,7 +25,6 @@ module.exports = config => {
 		src,
 		projectDst, // e.g.: ckeditor5/latest/api
 		outputDir, // build/docs
-		type, // type of API data (jsdoc, jsduck)
 		themePath, // Umberto theme path
 		BASE_PATH, // e.g.: ckeditor5/latest
 		docSearch, // Algolia's docsearch config
@@ -37,9 +36,10 @@ module.exports = config => {
 
 	const apiConfig = projectConfig.groups ? projectConfig.groups.find( g => g.id === 'api-reference' ) : null;
 	const middlewares = apiConfig ? apiConfig.middlewares : [];
-	const docSources = readDocSources( src, type );
+	const apiType = templateLocals.projectLocals.apiType;
+	const docSources = readDocSources( src, apiType );
 	const dataProvider = new DataProvider();
-	const dataCollection = dataProvider.convert( type, docSources, { middlewares } );
+	const dataCollection = dataProvider.convert( apiType, docSources, { middlewares } );
 	const projectName = projectConfig.name;
 
 	if ( !dataCollection ) {

package/src/tasks/build-documentation.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 
@@ -449,7 +449,6 @@ function buildApis( projectConfigs, options = {} ) {
 			src: upath.join( config.projectRootPath, config.path, apiConfig.sourceDir ),
 			projectDst: upath.join( BASE_PATH, apiConfig.slug ),
 			outputDir: hexoManager.getPublicDir().replace( process.cwd(), '' ),
-			type: apiConfig.type,
 			themePath: hexoManager.getThemePath(),
 			BASE_PATH,
 			docSearch: options.docSearch,
@@ -465,7 +464,8 @@ function buildApis( projectConfigs, options = {} ) {
 					disableSearch: config.docsearch === false,
 					repoUrl: config.repoUrl,
 					og: config.og,
-					projectSlug: config.slug
+					projectSlug: config.slug,
+					apiType: apiConfig.type
 				},
 				disableSearch: options.disableSearch,
 				googleoptimize: options.googleoptimize,

package/src/tasks/build-sdk.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/tasks/build-snippets.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/tasks/cache-files.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/tasks/compile-sass.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/tasks/copy-assets.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/tasks/copy-files.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/tasks/copy-project-docs.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */
 

package/src/tasks/copy-project-icons.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2017-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md.
  */