umberto 3.0.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "umberto",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "CKSource Documentation builder",
   "main": "src/index.js",
   "files": [
@@ -56,10 +56,10 @@
     "webpack": "^5.74.0"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-dev-bump-year": "^35.0.0",
-    "@ckeditor/ckeditor5-dev-ci": "^35.0.0",
-    "@ckeditor/ckeditor5-dev-docs": "^35.0.0",
-    "@ckeditor/ckeditor5-dev-release-tools": "^35.0.0",
+    "@ckeditor/ckeditor5-dev-bump-year": "^37.0.0",
+    "@ckeditor/ckeditor5-dev-ci": "^37.0.0",
+    "@ckeditor/ckeditor5-dev-docs": "^37.0.0",
+    "@ckeditor/ckeditor5-dev-release-tools": "^37.0.0",
     "browser-sync": "^2.27.10",
     "chai": "^4.3.6",
     "chokidar": "^3.5.3",

package/src/api-builder/classes/doc-data-factory.js

@@ -513,20 +513,26 @@ module.exports = class DocDataFactory {
 	 */
 	_processParams( data = [] ) {
 		const resultParams = data.slice(); // copy data array
-		const parentParams = []; // params which have sub-params; e.g. options
 
-		for ( const item of resultParams ) {
+		// Find properties that may contain nested properties.
+		const parentParams = resultParams.filter( item => {
 			if ( item.params ) {
-				continue;
+				return true;
 			}
 
-			// Parent params are of type 'Object'.
-			for ( const type of item.types ) {
-				if ( type === 'Object' ) {
-					parentParams.push( item );
+			return item.types.some( type => {
+				// An inline callback.
+				if ( type.type && type.type === 'function' ) {
+					return true;
 				}
-			}
-		}
+
+				if ( typeof type !== 'string' ) {
+					return false;
+				}
+
+				return type.toLowerCase() === 'object';
+			} );
+		} );
 
 		// For every parentParam gather its subparams.
 		for ( const parent of parentParams ) {
@@ -535,7 +541,7 @@ module.exports = class DocDataFactory {
 			for ( let i = 0; i < resultParams.length; i++ ) {
 				const item = resultParams[ i ];
 
-				if ( item.name && item.name.indexOf( `${ parent.name }.` ) !== -1 ) {
+				if ( item.name && item.name.includes( `${ parent.name }.` ) ) {
 					subParams.push( item );
 					// remove sub-params from main array, they will be kept under parentParam
 					resultParams.splice( i--, 1 );
@@ -549,6 +555,14 @@ module.exports = class DocDataFactory {
 			if ( parent.params.length > 0 ) {
 				parent.subParamsString = ' = { ';
 
+				if ( parent.types.length === 1 && parent.types[ 0 ].type === 'function' ) {
+					parent.subParamsString += renderInlineCallbackAsObjectProperty( parent.types[ 0 ] );
+
+					if ( subParams.length ) {
+						parent.subParamsString += ', ';
+					}
+				}
+
 				subParams.forEach( ( sub, index ) => {
 					parent.subParamsString += sub.optional ? `[${ sub.name }]` : sub.name;
 
@@ -752,3 +766,49 @@ function sortPartsAlphabetically( arr, criteria = [ {} ] ) {
 
 	return result;
 }
+
+/**
+ * This is a JavaScript version of the `renderInlineFunction()` pug mixin.
+ *
+ * See: themes/umberto/layout/_api-docs/_mixin/_type.pug.
+ *
+ * The goal is to render an inline object describing a callable type.
+ *
+ * @param {Object} type
+ * @param {Array.<String>} type.params
+ * @param {Array.<String>|String} type.returns
+ * @param {Boolean} type.isClass
+ * @returns {String}
+ */
+function renderInlineCallbackAsObjectProperty( type ) {
+	const { params, returns, isClass } = type;
+
+	return [
+		// Indicate if a function returns a class.
+		isClass ? 'new' : '',
+
+		// Parameters section.
+		'(',
+		params.map( mapToDocletCallback ).join( ', ' ),
+		')',
+
+		// Returns section.
+		' =&gt; ',
+
+		// Wraps an union in brackets.
+		Array.isArray( returns ) ? '(' : '',
+		Array.isArray( returns ) ? returns.map( mapToDocletCallback ).join( ' | ' ) : mapToDocletCallback( returns ),
+		Array.isArray( returns ) ? ')' : ''
+	].join( '' );
+
+	function mapToDocletCallback( param ) {
+		if ( !param.startsWith( 'module:' ) ) {
+			return param;
+		}
+
+		const href = param.replace( /:|\//g, '_' ).replace( '~', '-' ) + '.html';
+		const value = param.split( '~' )[ 1 ];
+
+		return `<a href="${ href }">${ value }</a>`;
+	}
+}

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

@@ -25,7 +25,8 @@ module.exports = class ModuleParser extends AbstractParser {
 			name: item.name,
 			longname: this.getLongName( item ),
 			kind: this.getKind( item ),
-			extraId: this.getExtraId( item )
+			extraId: this.getExtraId( item ),
+			file: this.getFile( item )
 		};
 	}
 };

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

@@ -127,7 +127,7 @@ class TypedocConverter {
 			}
 
 			if ( 'properties' in doclet ) {
-				doclet.properties = this._convertProperties( doclet, setSignature );
+				doclet.properties = this._convertProperties( setSignature );
 			}
 
 			if ( 'typeParameters' in doclet ) {
@@ -202,7 +202,7 @@ class TypedocConverter {
 		}
 
 		return signature.parameters
-			.map( item => {
+			.flatMap( item => {
 				const response = this._convertTypeToJsDoc( item );
 
 				response.name = item.name;
@@ -219,17 +219,29 @@ class TypedocConverter {
 					response.defaultvalue = item.defaultValue;
 				}
 
-				return response;
+				const nestedProperties = this._convertProperties( item );
+
+				if ( !nestedProperties ) {
+					return response;
+				}
+
+				return [
+					response,
+					...nestedProperties.map( nestedProperty => {
+						nestedProperty.name = `${ item.name }.${ nestedProperty.name }`;
+
+						return nestedProperty;
+					} )
+				];
 			} );
 	}
 
 	/**
 	 * @protected
-	 * @param {Object} doclet
 	 * @param {TypedocCallSignature} signature
 	 * @returns {Array|null}
 	 */
-	_convertProperties( doclet, signature ) {
+	_convertProperties( signature ) {
 		const types = signature.type.type === 'union' ? signature.type.types : [ signature.type ];
 		const type = types.find( type => type.declaration && type.declaration.children );
 
@@ -238,28 +250,30 @@ class TypedocConverter {
 		}
 
 		return type.declaration.children.map( child => {
-			const response = this._convertTypeToJsDoc( child );
+			// Nested properties cannot be duplicated so we can take the first signature when processing functions.
+			const childSignature = child.kindString === 'Method' ? child.signatures[ 0 ] : child;
+			const response = this._convertTypeToJsDoc( childSignature );
 
-			response.name = child.name;
+			response.name = childSignature.name;
 
 			if ( signature.comment && signature.comment.blockTags ) {
 				const atProperty = signature.comment.blockTags.find( blockTag => {
-					return blockTag.tag === '@property' && blockTag.name === child.name;
+					return blockTag.tag === '@property' && blockTag.name === childSignature.name;
 				} );
 
 				if ( atProperty ) {
 					response.description = TypedocConverter.convertComment( atProperty.content );
 				}
-			} else if ( child.comment && child.comment.summary ) {
-				response.description = TypedocConverter.convertComment( child.comment.summary );
+			} else if ( childSignature.comment && childSignature.comment.summary ) {
+				response.description = TypedocConverter.convertComment( childSignature.comment.summary );
 			}
 
-			if ( child.flags.isOptional ) {
+			if ( childSignature.flags.isOptional ) {
 				response.optional = true;
 			}
 
-			if ( child.defaultValue ) {
-				response.defaultvalue = child.defaultValue;
+			if ( childSignature.defaultValue ) {
+				response.defaultvalue = childSignature.defaultValue;
 			}
 
 			return response;
@@ -436,7 +450,7 @@ class TypeConverter {
 				};
 			}
 
-			const type = this.convert( parameter.type );
+			let type = this.convert( parameter.type );
 
 			// To avoid complex type parameters (they are available in typings provided by TypeScript),
 			// let's ignore unions.
@@ -447,6 +461,10 @@ class TypeConverter {
 				};
 			}
 
+			if ( parameter.default ) {
+				type += ` = ${ this.convertIntrinsicType( parameter.default ) }`;
+			}
+
 			return {
 				name: parameter.name,
 				isExtending: true,

package/themes/umberto/layout/_api-docs/_mixin/_method.pug

@@ -35,7 +35,8 @@ mixin method( met )
 							else
 								|  #{ param.name }
 							if ( param.subParamsString )
-								| #{ param.subParamsString }
+								//- Allow rendering HTML from the `subParamsString` as it may contain links to other pages.
+								| !{ param.subParamsString }
 							if index < met.params.length - 1
 								|,
 							else

package/themes/umberto/layout/_api-docs/_mixin/type-parameter.pug

@@ -5,7 +5,7 @@ mixin typeParameter( type )
 		code
 			span !{ type.name }
 
-			//- Most TypeScript types we mark as `object`, as they structure is complex.
+			//- We mark most TypeScript types as `object`, as their structure is complex.
 			//- Hence, it does not really make sense to show that a type extends an unknown `object`.
 			if ( type.value && type.value[ 0 ] !== 'object' )
 				| !{' : '}

package/themes/umberto/layout/_api-docs/_partial/type-parameters.pug

@@ -12,7 +12,7 @@ if isNonEmptyArray( data.typeParameters )
 						code
 							span( class="member-name" ) #{ type.name }
 
-							//- Most TypeScript types we mark as `object`, as they structure is complex.
+							//- We mark most TypeScript types as `object`, as their structure is complex.
 							//- Hence, it does not really make sense to show that a type extends an unknown `object`.
 							if ( type.value && type.value[ 0 ] !== 'object' )
 								| !{' : '}