@ckeditor/ckeditor5-dev-docs 34.1.3 → 35.0.0

package/lib/build.js

@@ -61,4 +61,12 @@ module.exports = async function build( config ) {
  * @property {String} [outputPath] A path to the place where extracted doclets will be saved. Is an optional value due to tests.
  *
  * @property {String} [extraPlugins=[]] An array of path to extra plugins that will be added to Typedoc.
+ *
+ * @property {TypedocValidator} [validatorOptions={}] An optional configuration object for validator.
+ */
+
+/**
+ * @typedef {Object} TypedocValidator
+ *
+ * @property {Boolean} [enableOverloadValidator=false] If set to `true`, the overloads validator will be enabled.
  */

package/lib/buildtypedoc.js

@@ -7,6 +7,8 @@
 
 const glob = require( 'fast-glob' );
 const TypeDoc = require( 'typedoc' );
+const { plugins } = require( '@ckeditor/typedoc-plugins' );
+
 const validators = require( './validators' );
 
 /**
@@ -19,6 +21,7 @@ module.exports = async function build( config ) {
 	const sourceFilePatterns = config.sourceFiles.filter( Boolean );
 	const strictMode = config.strict || false;
 	const extraPlugins = config.extraPlugins || [];
+	const validatorOptions = config.validatorOptions || {};
 
 	const files = await glob( sourceFilePatterns );
 	const typeDoc = new TypeDoc.Application();
@@ -49,19 +52,19 @@ module.exports = async function build( config ) {
 			// Fixes `"name": 'default" in the output project.
 			'typedoc-plugin-rename-defaults',
 
-			require.resolve( '@ckeditor/typedoc-plugins/lib/module-fixer' ),
-			require.resolve( '@ckeditor/typedoc-plugins/lib/symbol-fixer' ),
-			require.resolve( '@ckeditor/typedoc-plugins/lib/interface-augmentation-fixer' ),
-			require.resolve( '@ckeditor/typedoc-plugins/lib/tag-error' ),
-			require.resolve( '@ckeditor/typedoc-plugins/lib/tag-event' ),
-			require.resolve( '@ckeditor/typedoc-plugins/lib/tag-observable' ),
-			require.resolve( '@ckeditor/typedoc-plugins/lib/purge-private-api-docs' ),
+			plugins[ 'typedoc-plugin-module-fixer' ],
+			plugins[ 'typedoc-plugin-symbol-fixer' ],
+			plugins[ 'typedoc-plugin-interface-augmentation-fixer' ],
+			plugins[ 'typedoc-plugin-tag-error' ],
+			plugins[ 'typedoc-plugin-tag-event' ],
+			plugins[ 'typedoc-plugin-tag-observable' ],
+			plugins[ 'typedoc-plugin-purge-private-api-docs' ],
 
 			// The `event-inheritance-fixer` plugin must be loaded after `tag-event` plugin, as it depends on its output.
-			require.resolve( '@ckeditor/typedoc-plugins/lib/event-inheritance-fixer' ),
+			plugins[ 'typedoc-plugin-event-inheritance-fixer' ],
 
 			// The `event-param-fixer` plugin must be loaded after `tag-event` and `tag-observable` plugins, as it depends on their output.
-			require.resolve( '@ckeditor/typedoc-plugins/lib/event-param-fixer' ),
+			plugins[ 'typedoc-plugin-event-param-fixer' ],
 
 			...extraPlugins
 		]
@@ -75,7 +78,7 @@ module.exports = async function build( config ) {
 		throw 'Something went wrong with TypeDoc.';
 	}
 
-	const validationResult = validators.validate( conversionResult, typeDoc );
+	const validationResult = validators.validate( conversionResult, typeDoc, validatorOptions );
 
 	if ( !validationResult && strictMode ) {
 		throw 'Something went wrong with TypeDoc.';

package/lib/validators/fires-validator/index.js

@@ -6,7 +6,7 @@
 'use strict';
 
 const { ReflectionKind } = require( 'typedoc' );
-const { isReflectionValid, isIdentifierValid, isAbsoluteIdentifier } = require( '../utils' );
+const { utils } = require( '@ckeditor/typedoc-plugins' );
 
 /**
  * Validates the output produced by TypeDoc.
@@ -17,7 +17,9 @@ const { isReflectionValid, isIdentifierValid, isAbsoluteIdentifier } = require(
  * @param {Function} onError A callback that is executed when a validation error is detected.
  */
 module.exports = function validate( project, onError ) {
-	const reflections = project.getReflectionsByKind( ReflectionKind.Class | ReflectionKind.CallSignature ).filter( isReflectionValid );
+	const reflections = project
+		.getReflectionsByKind( ReflectionKind.Class | ReflectionKind.CallSignature )
+		.filter( utils.isReflectionValid );
 
 	for ( const reflection of reflections ) {
 		const identifiers = getIdentifiersFromFiresTag( reflection );
@@ -27,7 +29,7 @@ module.exports = function validate( project, onError ) {
 		}
 
 		for ( const identifier of identifiers ) {
-			const isValid = isIdentifierValid( reflection, identifier );
+			const isValid = utils.isIdentifierValid( reflection, identifier );
 
 			if ( !isValid ) {
 				const eventName = identifier.replace( /^#event:/, '' );
@@ -46,7 +48,7 @@ function getIdentifiersFromFiresTag( reflection ) {
 	return reflection.comment.getTags( '@fires' )
 		.flatMap( tag => tag.content.map( item => item.text.trim() ) )
 		.map( identifier => {
-			if ( isAbsoluteIdentifier( identifier ) ) {
+			if ( utils.isAbsoluteIdentifier( identifier ) ) {
 				return identifier;
 			}
 

package/lib/validators/index.js

@@ -5,30 +5,34 @@
 
 'use strict';
 
+const { utils } = require( '@ckeditor/typedoc-plugins' );
 const seeValidator = require( './see-validator' );
 const linkValidator = require( './link-validator' );
 const firesValidator = require( './fires-validator' );
-const overloadsValidator = require( './overloads-validator' );
 const moduleValidator = require( './module-validator' );
-const { getNode } = require( './utils' );
+const overloadsValidator = require( './overloads-validator' );
 
 /**
  * Validates the CKEditor 5 documentation.
  *
  * @param {Object} project Generated output from TypeDoc to validate.
  * @param {Object} typeDoc A TypeDoc application instance.
+ * @param {TypedocValidator} [options={}] A configuration object.
  * @returns {Boolean}
  */
 module.exports = {
-	validate( project, typeDoc ) {
+	validate( project, typeDoc, options = {} ) {
 		const validators = [
 			seeValidator,
 			linkValidator,
 			firesValidator,
-			overloadsValidator,
 			moduleValidator
 		];
 
+		if ( options.enableOverloadValidator ) {
+			validators.push( overloadsValidator );
+		}
+
 		typeDoc.logger.info( 'Starting validation...' );
 
 		// The same error can be reported twice:
@@ -39,7 +43,7 @@ module.exports = {
 
 		for ( const validator of validators ) {
 			validator( project, ( error, reflection ) => {
-				const node = getNode( reflection );
+				const node = utils.getNode( reflection );
 
 				errors.set( node, { error, node } );
 			} );

package/lib/validators/link-validator/index.js

@@ -6,7 +6,7 @@
 'use strict';
 
 const { ReflectionKind } = require( 'typedoc' );
-const { isReflectionValid, isIdentifierValid } = require( '../utils' );
+const { utils } = require( '@ckeditor/typedoc-plugins' );
 
 /**
  * Validates the output produced by TypeDoc.
@@ -17,7 +17,7 @@ const { isReflectionValid, isIdentifierValid } = require( '../utils' );
  * @param {Function} onError A callback that is executed when a validation error is detected.
  */
 module.exports = function validate( project, onError ) {
-	const reflections = project.getReflectionsByKind( ReflectionKind.All ).filter( isReflectionValid );
+	const reflections = project.getReflectionsByKind( ReflectionKind.All ).filter( utils.isReflectionValid );
 
 	for ( const reflection of reflections ) {
 		const identifiers = getIdentifiersFromLinkTag( reflection );
@@ -27,7 +27,7 @@ module.exports = function validate( project, onError ) {
 		}
 
 		for ( const identifier of identifiers ) {
-			const isValid = isIdentifierValid( reflection, identifier );
+			const isValid = utils.isIdentifierValid( reflection, identifier );
 
 			if ( !isValid ) {
 				onError( `Incorrect link: "${ identifier }"`, reflection );

package/lib/validators/module-validator/index.js

@@ -6,7 +6,7 @@
 'use strict';
 
 const { ReflectionKind } = require( 'typedoc' );
-const { getNode } = require( '../utils' );
+const { utils } = require( '@ckeditor/typedoc-plugins' );
 
 /**
  * Validates the output produced by TypeDoc.
@@ -27,7 +27,12 @@ module.exports = function validate( project, onError ) {
 			continue;
 		}
 
-		const filePath = getNode( reflection ).fileName;
+		const filePath = utils.getNode( reflection ).fileName;
+
+		if ( filePath.endsWith( 'src/augmentation.ts' ) ) {
+			continue;
+		}
+
 		const expectedFilePath = `ckeditor5-${ packageName }/src/${ moduleName.join( '/' ) }.ts`;
 
 		if ( !filePath.endsWith( expectedFilePath ) ) {

package/lib/validators/overloads-validator/index.js

@@ -6,7 +6,10 @@
 'use strict';
 
 const { ReflectionKind } = require( 'typedoc' );
-const { isReflectionValid } = require( '../utils' );
+const { utils } = require( '@ckeditor/typedoc-plugins' );
+
+// The `@label` validator is currently not used.
+// See: https://github.com/ckeditor/ckeditor5/issues/13591.
 
 /**
  * Validates the output produced by TypeDoc.
@@ -20,7 +23,7 @@ const { isReflectionValid } = require( '../utils' );
  */
 module.exports = function validate( project, onError ) {
 	const kinds = ReflectionKind.Method | ReflectionKind.Constructor | ReflectionKind.Function;
-	const reflections = project.getReflectionsByKind( kinds ).filter( isReflectionValid );
+	const reflections = project.getReflectionsByKind( kinds ).filter( utils.isReflectionValid );
 
 	for ( const reflection of reflections ) {
 		// Omit non-overloaded structures.

package/lib/validators/see-validator/index.js

@@ -6,7 +6,7 @@
 'use strict';
 
 const { ReflectionKind } = require( 'typedoc' );
-const { isReflectionValid, isIdentifierValid } = require( '../utils' );
+const { utils } = require( '@ckeditor/typedoc-plugins' );
 
 /**
  * Validates the output produced by TypeDoc.
@@ -17,7 +17,7 @@ const { isReflectionValid, isIdentifierValid } = require( '../utils' );
  * @param {Function} onError A callback that is executed when a validation error is detected.
  */
 module.exports = function validate( project, onError ) {
-	const reflections = project.getReflectionsByKind( ReflectionKind.All ).filter( isReflectionValid );
+	const reflections = project.getReflectionsByKind( ReflectionKind.All ).filter( utils.isReflectionValid );
 
 	for ( const reflection of reflections ) {
 		const identifiers = getIdentifiersFromSeeTag( reflection );
@@ -27,7 +27,7 @@ module.exports = function validate( project, onError ) {
 		}
 
 		for ( const identifier of identifiers ) {
-			const isValid = isIdentifierValid( reflection, identifier );
+			const isValid = utils.isIdentifierValid( reflection, identifier );
 
 			if ( !isValid ) {
 				onError( `Incorrect link: "${ identifier }"`, reflection );

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@ckeditor/ckeditor5-dev-docs",
-  "version": "34.1.3",
+  "version": "35.0.0",
   "description": "Tasks used to build and verify the documentation for CKEditor 5.",
   "keywords": [],
   "main": "lib/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-dev-utils": "^34.1.3",
-    "@ckeditor/jsdoc-plugins": "^34.1.3",
-    "@ckeditor/typedoc-plugins": "^34.1.3",
+    "@ckeditor/ckeditor5-dev-utils": "^35.0.0",
+    "@ckeditor/jsdoc-plugins": "^35.0.0",
+    "@ckeditor/typedoc-plugins": "^35.0.0",
     "fast-glob": "^3.2.4",
     "fs-extra": "^9.0.0",
     "jsdoc": "ckeditor/jsdoc#fixed-trailing-comment-doclets",

package/lib/validators/utils/index.js

@@ -1,205 +0,0 @@
-/**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md.
- */
-
-'use strict';
-
-/**
- * Common utils for TypeDoc validators.
- */
-module.exports = {
-	isReflectionValid,
-	isIdentifierValid,
-	isAbsoluteIdentifier,
-	getNode
-};
-
-/**
- * Checks if the reflection can be considered as "valid" (supported). Only reflections that are not nested inside a type are supported.
- *
- * @param {require('typedoc').Reflection} reflection The reflection to check if it is valid.
- * @returns {Boolean}
- */
-function isReflectionValid( reflection ) {
-	if ( reflection.name === '__type' ) {
-		return false;
-	}
-
-	if ( reflection.parent ) {
-		return isReflectionValid( reflection.parent );
-	}
-
-	return true;
-}
-
-/**
- * Checks if the name (identifier) that is provided for a tag, points to an existing reflection in the whole project.
- * The identifier can be either a relative or an absolute one.
- *
- * @param {require('typedoc').Reflection} reflection The reflection that contain given identifier.
- * @param {String} identifier An identifier to check.
- * @returns {Boolean}
- */
-function isIdentifierValid( reflection, identifier ) {
-	// We don't want to validate inherited identifiers, because they should be checked only once in the base class.
-	// Inherited reflections could contain identifiers (links) that are valid only in the base class and not in the derived class.
-	if ( reflection.inheritedFrom ) {
-		return true;
-	}
-
-	const absoluteIdentifier = isAbsoluteIdentifier( identifier ) ?
-		identifier :
-		toAbsoluteIdentifier( reflection, identifier );
-
-	return hasTarget( reflection.project, absoluteIdentifier );
-}
-
-/**
- * Checks if the identifier is an absolute one.
- *
- * @param {String} identifier An identifier to check.
- * @returns {Boolean}
- */
-function isAbsoluteIdentifier( identifier ) {
-	return identifier.startsWith( 'module:' );
-}
-
-/**
- * Converts a relative identifier into an absolute one.
- *
- * @param {require('typedoc').Reflection} reflection The reflection that contain given identifier.
- * @param {String} identifier An identifier to convert.
- * @returns {String}
- */
-function toAbsoluteIdentifier( reflection, identifier ) {
-	const separator = identifier[ 0 ];
-	const parts = getLongNameParts( reflection );
-
-	return separator === '~' ?
-		'module:' + parts[ 0 ] + identifier :
-		'module:' + parts[ 0 ] + '~' + parts[ 1 ] + identifier;
-}
-
-/**
- * Returns a longname for a reflection, divided into separate parts.
- *
- * @param {require('typedoc').Reflection} reflection A reflection for which we want to get its longname.
- * @returns {Array.<String>}
- */
-function getLongNameParts( reflection ) {
-	// Kinds of reflection that affect the longname format.
-	const kinds = [
-		'Module',
-		'Class',
-		'Function',
-		'Interface',
-		'Type alias',
-		'Accessor',
-		'Variable',
-		'Method',
-		'Property',
-		'Event'
-	];
-
-	const parts = [];
-
-	while ( reflection ) {
-		if ( kinds.includes( reflection.kindString ) ) {
-			parts.unshift( reflection.name );
-		}
-
-		reflection = reflection.parent;
-	}
-
-	return parts;
-}
-
-/**
- * Returns the TypeScript node from the reflection.
- *
- * @param {require('typedoc').Reflection} reflection A reflection for which we want to get its TypeScript node.
- * @returns {Object}
- */
-function getNode( reflection ) {
-	let symbol = reflection.project.getSymbolFromReflection( reflection );
-	let declarationIndex = 0;
-
-	if ( !symbol ) {
-		// The TypeDoc project does not store symbols for signatures. To get the TypeScript node from a signature, we need to get the
-		// symbol from its parent, which contains all nodes for each signature.
-		symbol = reflection.project.getSymbolFromReflection( reflection.parent );
-		declarationIndex = reflection.parent.signatures ? reflection.parent.signatures.indexOf( reflection ) : 0;
-	}
-
-	return symbol.declarations[ declarationIndex ];
-}
-
-/**
- * Checks if the provided identifier targets an existing reflection within the whole project.
- *
- * @param {require('typedoc').ProjectReflection} project The project reflection.
- * @param {String} identifier The absolute identifier to locate the target reflection.
- * @returns {Boolean}
- */
-function hasTarget( project, identifier ) {
-	const parts = identifier
-		// Remove leading "module:" prefix from the doclet longname.
-		.substring( 'module:'.length )
-		// Then, split the rest of the longname into separate parts.
-		.split( /#|~|\./ );
-
-	// The last part of the longname may contain a colon, which can be either a part of the event name, or it indicates that the name
-	// targets a labeled signature.
-	const lastPart = parts.pop();
-	const [ lastPartName, lastPartLabel ] = lastPart.split( ':' );
-
-	const isIdentifierEvent = lastPart.startsWith( 'event:' );
-	const isIdentifierLabeledSignature = !isIdentifierEvent && lastPart.includes( ':' );
-
-	if ( isIdentifierLabeledSignature ) {
-		// If the identifier is a labeled signature, just use the method/function name and the labeled signature will be searched later.
-		parts.push( lastPartName );
-	} else {
-		// Otherwise, restore the original identifier part.
-		parts.push( lastPart );
-	}
-
-	const targetReflection = project.getChildByName( parts );
-
-	if ( !targetReflection ) {
-		return false;
-	}
-
-	// Now, when the target reflection is found, do some checks whether it matches the identifier.
-	// (1) Check if the labeled signature targets an existing signature.
-	if ( isIdentifierLabeledSignature ) {
-		if ( !targetReflection.signatures ) {
-			return false;
-		}
-
-		return targetReflection.signatures.some( signature => {
-			if ( !signature.comment ) {
-				return false;
-			}
-
-			const labelTag = signature.comment.getTag( '@label' );
-
-			if ( !labelTag ) {
-				return false;
-			}
-
-			return labelTag.content[ 0 ].text === lastPartLabel;
-		} );
-	}
-
-	const isIdentifierStatic = identifier.includes( '.' );
-	const isTargetReflectionStatic = Boolean( targetReflection.flags && targetReflection.flags.isStatic );
-
-	// (2) Check if the static/non-static reflection flag matches the separator used in the identifier.
-	if ( isIdentifierStatic !== isTargetReflectionStatic ) {
-		return false;
-	}
-
-	return true;
-}