Merge branch 'epic/3757-esm' into i/3765-tests

README.md

@@ -20,8 +20,7 @@ This repository is a monorepo. It contains multiple npm packages.
 | [`@ckeditor/ckeditor5-dev-utils`](/packages/ckeditor5-dev-utils)                           | [![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-dev-utils.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-utils)                       |
 | [`@ckeditor/ckeditor5-dev-translations`](/packages/ckeditor5-dev-translations)             | [![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-dev-translations.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-translations)         |
 | [`@ckeditor/ckeditor5-dev-web-crawler`](/packages/ckeditor5-dev-web-crawler)               | [![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-dev-web-crawler.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-dev-web-crawler)           |
-| [`@ckeditor/jsdoc-plugins`](/packages/jsdoc-plugins)                                       | [![npm version](https://badge.fury.io/js/%40ckeditor%2Fjsdoc-plugins.svg)](https://www.npmjs.com/package/@ckeditor/jsdoc-plugins)                                   |
-| [`@ckeditor/typedoc-plugins`](/packages/typedoc-plugins)                                   | [![npm version](https://badge.fury.io/js/%40ckeditor%2Ftypedoc-plugins.svg)](https://www.npmjs.com/package/@ckeditor/jsdoc-plugins)                                 |
+| [`@ckeditor/typedoc-plugins`](/packages/typedoc-plugins)                                   | [![npm version](https://badge.fury.io/js/%40ckeditor%2Ftypedoc-plugins.svg)](https://www.npmjs.com/package/@ckeditor/typedoc-plugins)                                 |
 
 ## Cloning
 

packages/ckeditor5-dev-docs/lib/build.js

@@ -3,49 +3,96 @@
  * For licensing, see LICENSE.md.
  */
 
+import glob from 'fast-glob';
+import TypeDoc from 'typedoc';
+import typedocPlugins from '@ckeditor/typedoc-plugins';
+
+import validators from './validators/index.js';
+
 /**
- * Builds CKEditor 5 documentation.
+ * Builds CKEditor 5 documentation using `typedoc`.
  *
- * @param {JSDocConfig|TypedocConfig} config
+ * @param {TypedocConfig} config
  * @returns {Promise}
  */
 export default async function build( config ) {
-	const type = config.type || 'jsdoc';
-
-	if ( type === 'jsdoc' ) {
-		return ( await import( './buildjsdoc.js' ) ).default( config );
-	} else if ( type === 'typedoc' ) {
-		return ( await import( './buildtypedoc.js' ) ).default( config );
-	} else {
-		throw new Error( `Unknown documentation tool (${ type }).` );
+	const { plugins } = typedocPlugins;
+	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();
+
+	typeDoc.options.addReader( new TypeDoc.TSConfigReader() );
+	typeDoc.options.addReader( new TypeDoc.TypeDocReader() );
+
+	typeDoc.bootstrap( {
+		tsconfig: config.tsconfig,
+		excludeExternals: true,
+		entryPoints: files,
+		logLevel: 'Warn',
+		basePath: config.cwd,
+		blockTags: [
+			'@eventName',
+			'@default'
+		],
+		inlineTags: [
+			'@link',
+			'@glink'
+		],
+		modifierTags: [
+			'@publicApi',
+			'@skipSource',
+			'@internal'
+		],
+		plugin: [
+			// Fixes `"name": 'default" in the output project.
+			'typedoc-plugin-rename-defaults',
+
+			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.
+			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.
+			plugins[ 'typedoc-plugin-event-param-fixer' ],
+
+			...extraPlugins
+		]
+	} );
+
+	console.log( 'Typedoc started...' );
+
+	const conversionResult = typeDoc.convert();
+
+	if ( !conversionResult ) {
+		throw 'Something went wrong with TypeDoc.';
 	}
-}
 
-/**
- * @typedef {Object} JSDocConfig
- *
- * @property {'jsdoc'} type
- *
- * @property {Array.<String>} sourceFiles Glob pattern with source files.
- *
- * @property {String} readmePath Path to `README.md`.
- *
- * @property {Boolean} [validateOnly=false] Whether JSDoc should only validate the documentation and finish
- * with error code `1`. If not passed, the errors will be printed to the console but the task will finish with `0`.
- *
- * @property {Boolean} [strict=false] If `true`, errors found during the validation will finish the process
- * and exit code will be changed to `1`.
- *
- * @property {String} [outputPath='docs/api/output.json'] A path to the place where extracted doclets will be saved.
- *
- * @property {String} [extraPlugins=[]] An array of path to extra plugins that will be added to JSDoc.
- */
+	const validationResult = validators.validate( conversionResult, typeDoc, validatorOptions );
+
+	if ( !validationResult && strictMode ) {
+		throw 'Something went wrong with TypeDoc.';
+	}
+
+	if ( config.outputPath ) {
+		await typeDoc.generateJson( conversionResult, config.outputPath );
+	}
+
+	console.log( `Documented ${ files.length } files!` );
+}
 
 /**
  * @typedef {Object} TypedocConfig
  *
- * @property {'typedoc'} type
- *
  * @property {Object} config
  *
  * @property {String} cwd

packages/ckeditor5-dev-docs/package.json

@@ -23,11 +23,9 @@
   ],
   "dependencies": {
     "@ckeditor/ckeditor5-dev-utils": "^43.0.0",
-    "@ckeditor/jsdoc-plugins": "^43.0.0",
     "@ckeditor/typedoc-plugins": "^43.0.0",
     "fast-glob": "^3.2.4",
     "fs-extra": "^11.2.0",
-    "jsdoc": "ckeditor/jsdoc#fixed-trailing-comment-doclets",
     "tmp": "^0.2.1",
     "typedoc": "^0.23.15",
     "typedoc-plugin-rename-defaults": "0.6.6"

packages/ckeditor5-dev-docs/tests/validators/fires-validator/index.js

@@ -7,7 +7,7 @@ import { describe, it, expect, vi } from 'vitest';
 import { fileURLToPath } from 'url';
 import path from 'path';
 import testUtils from '../../_utils.js';
-import build from '../../../lib/buildtypedoc.js';
+import build from '../../../lib/build.js';
 
 const __filename = fileURLToPath( import.meta.url );
 const __dirname = path.dirname( __filename );
@@ -39,7 +39,6 @@ describe( 'dev-docs/validators/fires-validator', function() {
 
 	it( 'should warn if fired event does not exist', async () => {
 		await build( {
-			type: 'typedoc',
 			cwd: FIXTURES_PATH,
 			tsconfig: TSCONFIG_PATH,
 			sourceFiles: [ SOURCE_FILES ],

packages/ckeditor5-dev-docs/tests/validators/link-validator/index.js

@@ -7,7 +7,7 @@ import { describe, it, expect, vi } from 'vitest';
 import { fileURLToPath } from 'url';
 import path from 'path';
 import testUtils from '../../_utils.js';
-import build from '../../../lib/buildtypedoc.js';
+import build from '../../../lib/build.js';
 
 const __filename = fileURLToPath( import.meta.url );
 const __dirname = path.dirname( __filename );
@@ -40,7 +40,6 @@ describe( 'dev-docs/validators/link-validator', function() {
 
 	it( 'should warn if link is not valid', async () => {
 		await build( {
-			type: 'typedoc',
 			cwd: FIXTURES_PATH,
 			tsconfig: TSCONFIG_PATH,
 			sourceFiles: [ SOURCE_FILES ],
@@ -133,7 +132,6 @@ describe( 'dev-docs/validators/link-validator', function() {
 
 	it( 'should not call error callback for derived class when there are errors in inherited class', async () => {
 		await build( {
-			type: 'typedoc',
 			cwd: FIXTURES_PATH,
 			tsconfig: TSCONFIG_PATH,
 			sourceFiles: [ DERIVED_FILE ],

packages/ckeditor5-dev-docs/tests/validators/module-validator/index.js

@@ -7,7 +7,7 @@ import { describe, it, expect, vi } from 'vitest';
 import { fileURLToPath } from 'url';
 import path from 'path';
 import testUtils from '../../_utils.js';
-import build from '../../../lib/buildtypedoc.js';
+import build from '../../../lib/build.js';
 
 const __filename = fileURLToPath( import.meta.url );
 const __dirname = path.dirname( __filename );
@@ -39,7 +39,6 @@ describe( 'dev-docs/validators/module-validator', function() {
 
 	it( 'should warn if module name is not valid', async () => {
 		await build( {
-			type: 'typedoc',
 			cwd: FIXTURES_PATH,
 			tsconfig: TSCONFIG_PATH,
 			sourceFiles: [ SOURCE_FILES ],