umberto 2.2.0 → 2.3.1

package/src/api-builder/classes/description-parser.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.
  */
 
@@ -9,6 +9,8 @@ const { default: cheerio } = require( 'cheerio' );
 const splitLongname = require( '../../helpers/split-longname' );
 const chalk = require( 'chalk' );
 const macroReplacer = require( '../../tasks/macro-replacer' );
+const findTargetDoclet = require( '../utils/findtargetdoclet' );
+const { hasDedicatedApiPages, LONG_NAME_LABEL_REGEXP, LONG_NAME_MEMBER_SEPARATOR_REGEXP } = require( '../utils/utils' );
 
 /**
  * Class responsible for parsing doc descriptions.
@@ -102,107 +104,121 @@ module.exports = class DescriptionParser {
 
 	/**
 	 * Finds all {@link} and {@see} tags and converts them to links if possible. If not, converts to text.
+	 *
 	 * @param {String} str String to be parsed.
-	 * @param {Object} options.
+	 * @param {Object} options
 	 * @param {Doclet} options.doclet Parent doclet of currently processed item. Used to handle shorthand links.
+	 * @param {Doclet} options.parentDoclet Parent of the parent. Used to handle shorthand links.
+	 * @param {Boolean} options.asMember Whether the processed description is a child of the doclet.
 	 * @returns {String} result Parsed string.
 	 */
 	_parseJSDocLinks( str, options = {} ) {
-		const regex = /{(?:@link|@see)\s+([^\s}]+)\s*([^}]*)}/g;
-		let result = str;
+		const regex = /{(?:@link|@see)\s+([^{]+?(?:{[^}]+})?([^{}]*\\?))}/g;
 
 		if ( str.indexOf( '@link' ) === -1 && str.indexOf( '@see' ) === -1 ) {
-			return result;
+			return str;
 		}
 
+		let result = str;
 		let match = regex.exec( str );
-		let href;
 
 		while ( match !== null ) {
-			let [ fullMatch, longname, linkText ] = [ ...match ];
-			let { longnameBase, name } = splitLongname( longname );
+			const [ fullMatch ] = match;
+			let [ , longname, linkText ] = match[ 1 ].match( /^(\S+)\s*([\s\S]*)$/ );
+			let { longnameBase, name, label } = splitLongname( longname );
+			let structure, module, member, query;
 
 			if ( !options.asMember && ( longnameBase.startsWith( '~' ) || longname.startsWith( '~' ) || longname.startsWith( '#' ) ) ) {
-				// Special case of shorthand links, e.g. ~SomeClass#someMethod.
-				let itemName = name;
+				member = name;
+				query = { skipModule: true };
+				structure = options.parentDoclet ? options.parentDoclet.longname : options.doclet.memberof;
+
+				// Shorthand: `#someMethod`.
+				// TODO: Why `#` only? Can it start with `.` or `~`?
 				if ( longname.startsWith( '#' ) ) {
-					itemName = longname.slice( 1 );
-				}
+					member = longname.slice( 1 ).replace( LONG_NAME_LABEL_REGEXP, '' );
 
-				// Get a doclet to which we link.
-				const linkTargetDoclet = this._dataCollection.get( `ln:${ options.doclet.longname }#${ itemName }` ).getFirst() ||
-					this._dataCollection.get( `ln:${ options.doclet.longname }.${ itemName }` ).getFirst() ||
-					(
-						options.parentDoclet &&
-						this._dataCollection.get( `ln:${ options.parentDoclet.longname }#${ itemName }` ).getFirst()
-					);
-
-				if ( linkTargetDoclet ) {
-					href = `#${ linkTargetDoclet.extraId }`;
-				} else if ( !/[#.]/.test( longname ) ) {
-					href = '#';
-				} else {
-					href = `#${ name }`;
+					// It is needed due to the possible parsing of invalid links within the `@error` tag.
+					if ( options.doclet.longname ) {
+						structure = options.doclet.longname.split( LONG_NAME_MEMBER_SEPARATOR_REGEXP )[ 0 ];
+					}
+				}
+				// Shorthand: `~SomeClass#someMethod`.
+				// Use the doclet full name as a reference to the structure.
+				else if ( longname.startsWith( '~' ) ) {
+					if ( options.doclet.longname ) {
+						structure = options.doclet.longname.split( '~' )[ 0 ];
+
+						// When looking for a different structure within the same module, include its name to search for proper doclets.
+						if ( longnameBase ) {
+							structure += `~${ longnameBase }`;
+						}
+					} else if ( options.parentDoclet && options.parentDoclet.longname ) {
+						structure = options.parentDoclet.longname.split( '~' )[ 0 ];
+						member = longname.slice( 1 );
+					}
 				}
 			} else {
+				// Normalize the specified link expression when linking within the module or definition (class, interface, etc.) scope.
 				if ( options.asMember && ( longnameBase.startsWith( '~' ) || longname.startsWith( '~' ) || longname.startsWith( '#' ) ) ) {
-					longname = options.doclet.memberof + longname;
+					if ( longname.startsWith( '#' ) ) {
+						longname = options.doclet.longname + longname;
+					} else {
+						longname = options.doclet.memberof + longname;
+					}
+
 					const split = splitLongname( longname );
 					longnameBase = split.longnameBase;
 					name = split.name;
 				}
-				// Get a doclet to which we link.
-				const docletByLongname = this._dataCollection.get( `ln:${ longname }` ).getFirst();
-
-				// The link may use notation like: module~SomeClass#method-name, so try to get a doclet by extraId property.
-				// extraId property looks like: method-methodName, or property-propertyName etc.
-				const linkTargetDocletByExtraId = this._dataCollection.get( `id:${ longnameBase }#${ name }` ).getFirst() ||
-					this._dataCollection.get( `id:${ longnameBase }.${ name }` ).getFirst() ||
-					this._dataCollection.get( `id:${ longnameBase }~${ name }` ).getFirst();
-
-				if ( docletByLongname ) {
-					href = this._fileNameManager.getUrl( longname ) ||
-						this._fileNameManager.getUrl( longnameBase, docletByLongname.extraId );
-				} else if ( linkTargetDocletByExtraId ) {
-					href = this._fileNameManager.getUrl( longname ) ||
-						this._fileNameManager.getUrl( longnameBase, linkTargetDocletByExtraId.extraId );
-				} else {
-					// The link may be written wrong, so try getting the doclet by longname, using # . or ~.
-					const linkTargetDoclet = this._dataCollection.get( `ln:${ longnameBase }#${ name }` ).getFirst() ||
-						this._dataCollection.get( `ln:${ longnameBase }.${ name }` ).getFirst() ||
-						this._dataCollection.get( `ln:${ longnameBase }~${ name }` ).getFirst();
-
-					if ( linkTargetDoclet ) {
-						href = this._fileNameManager.getUrl( longname ) ||
-							this._fileNameManager.getUrl( longnameBase, linkTargetDoclet.extraId );
-					}
-				}
+
+				module = longname;
+				structure = longnameBase;
+				member = name;
 			}
 
-			if ( href ) {
-				let linkContent;
+			const targetDoclet = findTargetDoclet( this._dataCollection, { module, structure, member, label, query } );
+			let replaceToPhrase;
 
-				if ( linkText ) {
-					linkContent = linkText.replace( 'event:', 'event-' );
+			if ( targetDoclet ) {
+				let href;
+
+				if ( hasDedicatedApiPages( targetDoclet ) ) {
+					href = this._fileNameManager.getUrl( targetDoclet.longname );
 				} else {
+					href = [
+						this._fileNameManager.getUrl( targetDoclet.memberof ),
+						encodeURI( targetDoclet.extraId )
+					].join( '#' );
+				}
+
+				if ( !linkText[ 3 ] && targetDoclet.kind === 'event' ) {
+					linkText = `event-${ targetDoclet.name }`;
+				}
+
+				let linkContent = linkText;
+
+				if ( !linkText ) {
 					linkContent = `<code>${ splitLongname( longname.replace( 'event:', 'event-' ) ).name }</code>`;
 				}
 
-				const linkHtml = `<a href="${ href }">${ linkContent }</a>`;
-				result = result.replace( fullMatch, linkHtml );
+				replaceToPhrase = `<a href="${ href }">${ linkContent }</a>`;
 			} else {
-				console.log( `${ chalk.yellow( 'Warning: ' ) }Invalid link in API docs: ${ chalk.gray( fullMatch ) }.`,
-					'There is no doclet of the link target.' );
+				console.log(
+					`${ chalk.yellow( 'Warning:' ) } Invalid link in API docs: ${ chalk.gray( fullMatch ) }.`,
+					'There is no doclet of the link target.'
+				);
 
 				options.buildInfo.warningCount += 1;
 
 				if ( linkText ) {
-					result = result.replace( fullMatch, `<code>${ linkText } (${ longname })</code>` );
+					replaceToPhrase = `<code>${ linkText } (${ longname })</code>`;
 				} else {
-					result = result.replace( fullMatch, `<code>${ longname }</code>` );
+					replaceToPhrase = `<code>${ longname }</code>`;
 				}
 			}
 
+			result = result.replace( fullMatch, replaceToPhrase );
 			match = regex.exec( str );
 		}
 

package/src/api-builder/classes/doc-data-factory.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.
  */
 
@@ -115,15 +115,34 @@ module.exports = class DocDataFactory {
 	 * @returns {Object}
 	 */
 	getClassShort( doclet, asMember = false ) {
+		const base = this._getBase( doclet, {
+			skipDescription: true
+		} );
+
 		const description = this._descriptionParser.parseDescription( doclet.description, {
 			doclet,
 			asMember,
 			buildInfo: this._options.buildInfo
 		} );
 
-		return Object.assign( this._getBase( doclet, { skipDescription: true } ), {
+		const itemData = {
 			description
-		} );
+		};
+
+		if ( doclet.typeParameters ) {
+			itemData.typeParameters = doclet.typeParameters.map( typeParameter => {
+				if ( typeParameter.description ) {
+					typeParameter.description = this._descriptionParser.parseDescription( typeParameter.description, {
+						doclet,
+						buildInfo: this._options.buildInfo
+					} );
+				}
+
+				return typeParameter;
+			} );
+		}
+
+		return Object.assign( base, itemData );
 	}
 
 	/**
@@ -195,6 +214,8 @@ module.exports = class DocDataFactory {
 			itemData.returns = this._getMembers( doclet.returns );
 		}
 
+		itemData.typeParameters = doclet.typeParameters || null;
+
 		return Object.assign( base, itemData );
 	}
 
@@ -243,7 +264,7 @@ module.exports = class DocDataFactory {
 		const methods = classMembersCollection.get( 'function' );
 		const events = classMembersCollection.get( 'event' );
 		const configOptionsProcessed = this._getMembers( configOptions, { parentDoclet: doclet } );
-		// Sorting properties alphabetically and also public > protected > private.
+		// Sorting properties alphabetically and also public > internal > protected > private.
 		const propertiesProcessed = sortPartsAlphabetically(
 			this._getMembers( properties, { parentDoclet: doclet } ),
 			[
@@ -251,6 +272,10 @@ module.exports = class DocDataFactory {
 					key: 'access',
 					value: 'public'
 				},
+				{
+					key: 'access',
+					value: 'internal'
+				},
 				{
 					key: 'access',
 					value: 'protected'
@@ -275,6 +300,10 @@ module.exports = class DocDataFactory {
 					key: 'access',
 					value: 'public'
 				},
+				{
+					key: 'access',
+					value: 'internal'
+				},
 				{
 					key: 'access',
 					value: 'protected'
@@ -289,6 +318,8 @@ module.exports = class DocDataFactory {
 		const staticMethods = Array.isArray( methodsProcessed ) ? methodsProcessed.filter( m => m.scope === 'static' ) : [];
 		const instanceMethods = Array.isArray( methodsProcessed ) ? methodsProcessed.filter( m => m.scope !== 'static' ) : [];
 		const augmentsNested = doclet.augmentsNested ? doclet.augmentsNested : [];
+		const typeParameters = doclet.typeParameters || null;
+
 		augmentsNested.unshift( doclet.longname );
 		augmentsNested.reverse();
 
@@ -300,6 +331,7 @@ module.exports = class DocDataFactory {
 			methods: methodsProcessed,
 			staticMethods,
 			instanceMethods,
+			typeParameters,
 			events: this._getMembers( events, {
 				callback: item => {
 					item.name = item.name.replace( 'event:', '' );
@@ -391,11 +423,12 @@ module.exports = class DocDataFactory {
 		itemData.readonly = doclet.readonly;
 		itemData.defaultvalue = typeof doclet.defaultvalue !== 'undefined' && doclet.defaultvalue !== null ?
 			doclet.defaultvalue.toString() : null;
+		itemData.label = doclet.label;
 		itemData.optional = doclet.optional;
 		itemData.scope = doclet.scope;
 		itemData.fires = doclet.fires;
-
 		itemData.types = getTypes( doclet );
+		itemData.typeParameters = doclet.typeParameters || null;
 
 		if ( doclet.params ) {
 			itemData.params = this._getMembers( doclet.params, { parentDoclet: options.parentDoclet } );
@@ -431,6 +464,19 @@ module.exports = class DocDataFactory {
 			} );
 		}
 
+		if ( doclet.typeParameters ) {
+			itemData.typeParameters = doclet.typeParameters.map( typeParameter => {
+				if ( typeParameter.description ) {
+					typeParameter.description = this._descriptionParser.parseDescription( typeParameter.description, {
+						doclet: options.parentDoclet,
+						buildInfo: this._options.buildInfo
+					} );
+				}
+
+				return typeParameter;
+			} );
+		}
+
 		return Object.assign( base, itemData );
 	}
 
@@ -586,6 +632,13 @@ function prepareBadges( item, context ) {
 			} );
 			break;
 
+		case 'internal':
+			badges.push( {
+				class: 'orange',
+				text: 'internal'
+			} );
+			break;
+
 		case 'protected':
 			badges.push( {
 				class: 'orange',

package/src/api-builder/classes/file-name-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/api-builder/classes/html-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/api-builder/classes/navigation-tree.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/api-builder/classes/tree-node.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/api-builder/utils/findtargetdoclet.js

@@ -0,0 +1,84 @@
+/**
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+/**
+ * A helper function used for searching for a proper doclet structure when creating a link
+ * from a guide or an API page.
+ *
+ * The main goal of this function is to avoid editing the same logic in many places.
+ *
+ * @param {DataCollection} docletCollection
+ * @param {Object} options
+ * @param {String} [options.module]
+ * @param {String} [options.structure]
+ * @param {String} options.member
+ * @param {String} [options.label]
+ * @param {Object} [options.query={}]
+ * @param {Boolean} [options.query.skipModule=false]
+ * @param {Boolean} [options.query.memberOnly=false]
+ * @returns {Object|null}
+ */
+module.exports = function findTargetDoclet( docletCollection, options ) {
+	const { module, structure, member, label, query } = options;
+	const { skipModule, memberOnly } = ( query || {} );
+
+	if ( !structure ) {
+		return null;
+	}
+
+	// Try to find an instance member...
+	let collection = docletCollection.get( `ln:${ structure }#${ member }` );
+
+	// ...or a static member.
+	if ( collection.isEmpty ) {
+		collection = docletCollection.get( `ln:${ structure }.${ member }` );
+	}
+
+	// When the advanced search is enabled, try to find also...
+	if ( !memberOnly ) {
+		// ...a definition within the same module.
+		if ( collection.isEmpty ) {
+			collection = docletCollection.get( `ln:${ structure }~${ member }` );
+		}
+
+		// To save a backward compatibility, let's try to find a structure without defining a member.
+		if ( collection.isEmpty && structure.endsWith( '~' + member ) ) {
+			collection = docletCollection.get( `ln:${ structure }` );
+		}
+
+		// Then, search for an event declaration (`...~Classname#event:eventName`).
+		if ( collection.isEmpty && member === 'event' ) {
+			collection = docletCollection.get( `ln:${ structure }#${ member }:${ label }` );
+		}
+
+		// (`...~Classname#eventName`). CKEditor 4 / JSDuck.
+		if ( collection.isEmpty && member === 'event' ) {
+			collection = docletCollection.get( `ln:${ structure }#${ label }` );
+		}
+
+		// Search for a module definition only if requested.
+		if ( !skipModule && collection.isEmpty ) {
+			collection = docletCollection.get( `ln:${ module }` );
+		}
+	}
+
+	if ( collection.isEmpty ) {
+		return null;
+	}
+
+	let targetDoclet;
+
+	if ( label && collection.size > 1 ) {
+		targetDoclet = collection.getByLabel( label );
+	}
+
+	if ( !targetDoclet ) {
+		targetDoclet = collection.getFirst();
+	}
+
+	return targetDoclet;
+};

package/src/api-builder/utils/utils.js

@@ -0,0 +1,41 @@
+/**
+ * @license Copyright (c) 2017-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+'use strict';
+
+const DEDICATED_PAGE_DOCLET_KINDS = [
+	'module', 'class', 'typedef', 'mixin', 'interface', 'namespace'
+];
+
+/**
+ * Set of utils used in helpers to generate links to API definitions.
+ */
+module.exports = {
+	/**
+	 * A regular expression used for extracting a member name from doclet full name, member of or just a name.
+	 */
+	MEMBER_NAME_REGEXP: /([{}\-\w$]+)(?::([A-Z0-9a-z_:{}]+))?$/,
+	//                               ^ Sync with the `LONG_NAME_LABEL_REGEXP` value.
+
+	/**
+	 * A regular expression used for removing a label (if specified) from a member name.
+	 * The regexp is used in `MEMBER_NAME_REGEXP` as a group, so the particular group should be synced.
+	 */
+	LONG_NAME_LABEL_REGEXP: /(?::([A-Z0-9a-z_:{}]+))?$/,
+
+	/**
+	 * A regular expression used for separating a definition (a class, an interface, etc.) and a member name.
+	 */
+	LONG_NAME_MEMBER_SEPARATOR_REGEXP: /[#.]/,
+
+	/**
+	 * @param {Object} doclet
+	 * @param {String} doclet.kind
+	 * @returns {Boolean}
+	 */
+	hasDedicatedApiPages( doclet ) {
+		return DEDICATED_PAGE_DOCLET_KINDS.includes( doclet.kind );
+	}
+};

package/src/data-converter/converters/jsdoc2umberto.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,13 @@ module.exports = data => {
 	}
 
 	parsed.forEach( ( item, index ) => {
+		if ( item.kind === 'event' ) {
+			// Remove `event:` from an event name.
+			if ( item.name.startsWith( 'event' ) ) {
+				item.name = item.name.replace( /^event[:-]/, '' );
+			}
+		}
+
 		if ( item.classdesc ) {
 			const description = item.classdesc;
 			delete parsed[ index ].classdesc;

package/src/data-converter/converters/jsduck2umberto.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.
  */