@ckeditor/ckeditor5-dev-docs 43.0.0-alpha.0 → 44.0.0-alpha.0

package/lib/build.js

@@ -3,51 +3,96 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
+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}
  */
-module.exports = async function build( config ) {
-	const type = config.type || 'jsdoc';
-
-	if ( type === 'jsdoc' ) {
-		return require( './buildjsdoc' )( config );
-	} else if ( type === 'typedoc' ) {
-		return require( './buildtypedoc' )( config );
-	} else {
-		throw new Error( `Unknown documentation tool (${ type }).` );
+export default async function build( config ) {
+	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

package/lib/index.js

@@ -3,10 +3,4 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-const build = require( './build' );
-
-module.exports = {
-	build
-};
+export { default as build } from './build.js';

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

@@ -3,10 +3,8 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-const { ReflectionKind } = require( 'typedoc' );
-const { utils } = require( '@ckeditor/typedoc-plugins' );
+import { ReflectionKind } from 'typedoc';
+import typedocPlugins from '@ckeditor/typedoc-plugins';
 
 /**
  * Validates the output produced by TypeDoc.
@@ -16,7 +14,8 @@ const { utils } = require( '@ckeditor/typedoc-plugins' );
  * @param {Object} project Generated output from TypeDoc to validate.
  * @param {Function} onError A callback that is executed when a validation error is detected.
  */
-module.exports = function validate( project, onError ) {
+export default function validate( project, onError ) {
+	const { utils } = typedocPlugins;
 	const reflections = project
 		.getReflectionsByKind( ReflectionKind.Class | ReflectionKind.CallSignature )
 		.filter( utils.isReflectionValid );
@@ -38,9 +37,11 @@ module.exports = function validate( project, onError ) {
 			}
 		}
 	}
-};
+}
 
 function getIdentifiersFromFiresTag( reflection ) {
+	const { utils } = typedocPlugins;
+
 	if ( !reflection.comment ) {
 		return [];
 	}

package/lib/validators/index.js

@@ -3,14 +3,12 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-const { utils } = require( '@ckeditor/typedoc-plugins' );
-const seeValidator = require( './see-validator' );
-const linkValidator = require( './link-validator' );
-const firesValidator = require( './fires-validator' );
-const moduleValidator = require( './module-validator' );
-const overloadsValidator = require( './overloads-validator' );
+import typedocPlugins from '@ckeditor/typedoc-plugins';
+import seeValidator from './see-validator/index.js';
+import linkValidator from './link-validator/index.js';
+import firesValidator from './fires-validator/index.js';
+import moduleValidator from './module-validator/index.js';
+import overloadsValidator from './overloads-validator/index.js';
 
 /**
  * Validates the CKEditor 5 documentation.
@@ -20,8 +18,9 @@ const overloadsValidator = require( './overloads-validator' );
  * @param {TypedocValidator} [options={}] A configuration object.
  * @returns {Boolean}
  */
-module.exports = {
+export default {
 	validate( project, typeDoc, options = {} ) {
+		const { utils } = typedocPlugins;
 		const validators = [
 			seeValidator,
 			linkValidator,

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

@@ -3,10 +3,8 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-const { ReflectionKind } = require( 'typedoc' );
-const { utils } = require( '@ckeditor/typedoc-plugins' );
+import { ReflectionKind } from 'typedoc';
+import typedocPlugins from '@ckeditor/typedoc-plugins';
 
 /**
  * Validates the output produced by TypeDoc.
@@ -16,7 +14,8 @@ const { utils } = require( '@ckeditor/typedoc-plugins' );
  * @param {Object} project Generated output from TypeDoc to validate.
  * @param {Function} onError A callback that is executed when a validation error is detected.
  */
-module.exports = function validate( project, onError ) {
+export default function validate( project, onError ) {
+	const { utils } = typedocPlugins;
 	const reflections = project.getReflectionsByKind( ReflectionKind.All ).filter( utils.isReflectionValid );
 
 	for ( const reflection of reflections ) {
@@ -34,7 +33,7 @@ module.exports = function validate( project, onError ) {
 			}
 		}
 	}
-};
+}
 
 function getIdentifiersFromLinkTag( reflection ) {
 	if ( !reflection.comment ) {

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

@@ -3,10 +3,8 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-const { ReflectionKind } = require( 'typedoc' );
-const { utils } = require( '@ckeditor/typedoc-plugins' );
+import { ReflectionKind } from 'typedoc';
+import typedocPlugins from '@ckeditor/typedoc-plugins';
 
 const AUGMENTATION_MODULE_REGEXP = /[^\\/]+[\\/]src[\\/]augmentation/;
 
@@ -18,7 +16,8 @@ const AUGMENTATION_MODULE_REGEXP = /[^\\/]+[\\/]src[\\/]augmentation/;
  * @param {Object} project Generated output from TypeDoc to validate.
  * @param {Function} onError A callback that is executed when a validation error is detected.
  */
-module.exports = function validate( project, onError ) {
+export default function validate( project, onError ) {
+	const { utils } = typedocPlugins;
 	const reflections = project.getReflectionsByKind( ReflectionKind.Module );
 
 	for ( const reflection of reflections ) {
@@ -53,4 +52,4 @@ module.exports = function validate( project, onError ) {
 			onError( `Invalid module name: "${ reflection.name }"`, reflection );
 		}
 	}
-};
+}

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

@@ -3,10 +3,8 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-const { ReflectionKind } = require( 'typedoc' );
-const { utils } = require( '@ckeditor/typedoc-plugins' );
+import { ReflectionKind } from 'typedoc';
+import typedocPlugins from '@ckeditor/typedoc-plugins';
 
 // The `@label` validator is currently not used.
 // See: https://github.com/ckeditor/ckeditor5/issues/13591.
@@ -21,7 +19,8 @@ const { utils } = require( '@ckeditor/typedoc-plugins' );
  * @param {Object} project Generated output from TypeDoc to validate.
  * @param {Function} onError A callback that is executed when a validation error is detected.
  */
-module.exports = function validate( project, onError ) {
+export default function validate( project, onError ) {
+	const { utils } = typedocPlugins;
 	const kinds = ReflectionKind.Method | ReflectionKind.Constructor | ReflectionKind.Function;
 	const reflections = project.getReflectionsByKind( kinds ).filter( utils.isReflectionValid );
 
@@ -52,4 +51,4 @@ module.exports = function validate( project, onError ) {
 			}
 		}
 	}
-};
+}

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

@@ -3,10 +3,8 @@
  * For licensing, see LICENSE.md.
  */
 
-'use strict';
-
-const { ReflectionKind } = require( 'typedoc' );
-const { utils } = require( '@ckeditor/typedoc-plugins' );
+import { ReflectionKind } from 'typedoc';
+import typedocPlugins from '@ckeditor/typedoc-plugins';
 
 /**
  * Validates the output produced by TypeDoc.
@@ -16,7 +14,8 @@ const { utils } = require( '@ckeditor/typedoc-plugins' );
  * @param {Object} project Generated output from TypeDoc to validate.
  * @param {Function} onError A callback that is executed when a validation error is detected.
  */
-module.exports = function validate( project, onError ) {
+export default function validate( project, onError ) {
+	const { utils } = typedocPlugins;
 	const reflections = project.getReflectionsByKind( ReflectionKind.All ).filter( utils.isReflectionValid );
 
 	for ( const reflection of reflections ) {
@@ -34,7 +33,7 @@ module.exports = function validate( project, onError ) {
 			}
 		}
 	}
-};
+}
 
 function getIdentifiersFromSeeTag( reflection ) {
 	if ( !reflection.comment ) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-dev-docs",
-  "version": "43.0.0-alpha.0",
+  "version": "44.0.0-alpha.0",
   "description": "Tasks used to build and verify the documentation for CKEditor 5.",
   "keywords": [],
   "author": "CKSource (http://cksource.com/)",
@@ -16,17 +16,16 @@
     "node": ">=18.0.0",
     "npm": ">=5.7.1"
   },
+  "type": "module",
   "main": "lib/index.js",
   "files": [
     "lib"
   ],
   "dependencies": {
-    "@ckeditor/ckeditor5-dev-utils": "^43.0.0-alpha.0",
-    "@ckeditor/jsdoc-plugins": "^43.0.0-alpha.0",
-    "@ckeditor/typedoc-plugins": "^43.0.0-alpha.0",
+    "@ckeditor/ckeditor5-dev-utils": "^44.0.0-alpha.0",
+    "@ckeditor/typedoc-plugins": "^44.0.0-alpha.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"

package/lib/buildjsdoc.js

@@ -1,93 +0,0 @@
-/**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md.
- */
-
-'use strict';
-
-const fs = require( 'fs-extra' );
-const tmp = require( 'tmp' );
-const glob = require( 'fast-glob' );
-const { tools } = require( '@ckeditor/ckeditor5-dev-utils' );
-
-/**
- * Builds CKEditor 5 documentation using `jsdoc`.
- *
- * @param {JSDocConfig} config
- * @returns {Promise}
- */
-module.exports = async function build( config ) {
-	const sourceFilePatterns = [
-		config.readmePath,
-		...config.sourceFiles
-	];
-
-	const extraPlugins = config.extraPlugins || [];
-	const outputPath = config.outputPath || 'docs/api/output.json';
-	const validateOnly = config.validateOnly || false;
-	const strictCheck = config.strict || false;
-
-	// Pass options to plugins via env variables.
-	// Since plugins are added using `require` calls other forms are currently impossible.
-	process.env.JSDOC_OUTPUT_PATH = outputPath;
-
-	if ( validateOnly ) {
-		process.env.JSDOC_VALIDATE_ONLY = 'true';
-	}
-
-	if ( strictCheck ) {
-		process.env.JSDOC_STRICT_CHECK = 'true';
-	}
-
-	const files = await glob( sourceFilePatterns );
-
-	const jsDocConfig = {
-		plugins: [
-			require.resolve( 'jsdoc/plugins/markdown' ),
-			require.resolve( '@ckeditor/jsdoc-plugins/lib/purge-private-api-docs' ),
-			require.resolve( '@ckeditor/jsdoc-plugins/lib/export-fixer/export-fixer' ),
-			require.resolve( '@ckeditor/jsdoc-plugins/lib/custom-tags/error' ),
-			require.resolve( '@ckeditor/jsdoc-plugins/lib/custom-tags/observable' ),
-			require.resolve( '@ckeditor/jsdoc-plugins/lib/observable-event-provider' ),
-			require.resolve( '@ckeditor/jsdoc-plugins/lib/longname-fixer/longname-fixer' ),
-			require.resolve( '@ckeditor/jsdoc-plugins/lib/fix-code-snippets' ),
-			require.resolve( '@ckeditor/jsdoc-plugins/lib/relation-fixer' ),
-			require.resolve( '@ckeditor/jsdoc-plugins/lib/event-extender/event-extender' ),
-			require.resolve( '@ckeditor/jsdoc-plugins/lib/cleanup' ),
-			require.resolve( '@ckeditor/jsdoc-plugins/lib/validator/validator' ),
-			require.resolve( '@ckeditor/jsdoc-plugins/lib/utils/doclet-logger' ),
-			...extraPlugins
-		],
-		source: {
-			include: files
-		},
-		opts: {
-			encoding: 'utf8',
-			recurse: true,
-			access: 'all',
-			template: 'templates/silent'
-		}
-	};
-
-	const tmpConfig = tmp.fileSync();
-
-	await fs.writeFile( tmpConfig.name, JSON.stringify( jsDocConfig ) );
-
-	console.log( 'JSDoc started...' );
-
-	try {
-		// Not so beautiful API as for 2020...
-		// See more in https://github.com/jsdoc/jsdoc/issues/938.
-		const cmd = require.resolve( 'jsdoc/jsdoc.js' );
-
-		// The `node` command is used for explicitly needed for Windows.
-		// See https://github.com/ckeditor/ckeditor5/issues/7212.
-		tools.shExec( `node ${ cmd } -c ${ tmpConfig.name }`, { verbosity: 'info' } );
-	} catch ( error ) {
-		console.error( 'An error was thrown by JSDoc:' );
-
-		throw error;
-	}
-
-	console.log( `Documented ${ files.length } files!` );
-};

package/lib/buildtypedoc.js

@@ -1,92 +0,0 @@
-/**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md.
- */
-
-'use strict';
-
-const glob = require( 'fast-glob' );
-const TypeDoc = require( 'typedoc' );
-const { plugins } = require( '@ckeditor/typedoc-plugins' );
-
-const validators = require( './validators' );
-
-/**
- * Builds CKEditor 5 documentation using `typedoc`.
- *
- * @param {TypedocConfig} config
- * @returns {Promise}
- */
-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();
-
-	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.';
-	}
-
-	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!` );
-};