Browse Source

API docs.

Piotrek Koszuliński 10 years ago
parent
commit
36372e6070
2 changed files with 72 additions and 5 deletions
  1. 27 1
      dev/tasks/gulp/build.js
  2. 45 4
      dev/tasks/gulp/utils.js

+ 27 - 1
dev/tasks/gulp/build.js

@@ -29,31 +29,57 @@ const minimist = require( 'minimist' );
 const utils = require( './utils' );
 
 const sep = path.sep;
-
 const options = minimist( process.argv.slice( 2 ), KNOWN_OPTIONS[ process.argv[ 2 ] ] );
 
 module.exports = ( config ) => {
 	const distDir = path.join( config.ROOT_DIR, config.DIST_DIR );
 
 	const tasks = {
+		/**
+		 * Removes the dist directory.
+		 */
 		clean() {
 			return del( distDir );
 		},
 
 		src: {
+			/**
+			 * Returns a stream of all source files.
+			 *
+			 * @param {Boolean} [watch] Whether the files should be watched.
+			 * @returns {Stream}
+			 */
 			all( watch ) {
 				return merge( tasks.src.main( watch ), tasks.src.ckeditor5( watch ), tasks.src.modules( watch ) );
 			},
 
+			/**
+			 * Returns a stream with just the main file (`ckeditor5/ckeditor.js`).
+			 *
+			 * @param {Boolean} [watch] Whether the files should be watched.
+			 * @returns {Stream}
+			 */
 			main( watch ) {
 				return utils.src( config.ROOT_DIR, 'ckeditor.js', watch );
 			},
 
+			/**
+			 * Returns a stream of all source files from CKEditor 5.
+			 *
+			 * @param {Boolean} [watch] Whether the files should be watched.
+			 * @returns {Stream}
+			 */
 			ckeditor5( watch ) {
 				return utils.src( config.ROOT_DIR, 'src/**/*.js', watch )
 					.pipe( utils.wrapCKEditor5Module() );
 			},
 
+			/**
+			 * Returns a stream of all source files from CKEditor 5 dependencies.
+			 *
+			 * @param {Boolean} [watch] Whether the files should be watched.
+			 * @returns {Stream}
+			 */
 			modules( watch ) {
 				const modulePathPattern = new RegExp( `node_modules${ sep }(ckeditor5-[^${ sep }]+)${ sep }src` );
 

+ 45 - 4
dev/tasks/gulp/utils.js

@@ -15,8 +15,16 @@ const stream = require( 'stream' );
 const sep = path.sep;
 
 const utils = {
-	src( root, pattern, watch ) {
-		const srcDir = path.join( root, pattern );
+	/**
+	 * Returns a stream of files matching the given glob pattern.
+	 *
+	 * @param {String} root The root directory.
+	 * @param {String} glob The glob pattern.
+	 * @param {Boolean} [watch] Whether to watch the files.
+	 * @returns {Stream}
+	 */
+	src( root, glob, watch ) {
+		const srcDir = path.join( root, glob );
 		let stream = gulp.src( srcDir );
 
 		if ( watch ) {
@@ -29,12 +37,25 @@ const utils = {
 		return stream;
 	},
 
+	/**
+	 * Saves the files piped into this stream to the `dist/` directory.
+	 *
+	 * @param {String} distDir The `dist/` directory path.
+	 * @param {String} format The format of the distribution (`esnext`, `amd`, or `cjs`).
+	 * @returns {Stream}
+	 */
 	dist( distDir, format ) {
 		const destDir = path.join( distDir, format );
 
 		return gulp.dest( destDir );
 	},
 
+	/**
+	 * Transpiles files piped into this stream to the given format (`amd` or `cjs`).
+	 *
+	 * @param {String} format
+	 * @returns {Stream}
+	 */
 	transpile( format ) {
 		const babelModuleTranspilers = {
 			amd: 'amd',
@@ -47,12 +68,21 @@ const utils = {
 		}
 
 		return new stream.PassThrough( { objectMode: true } )
-			.pipe( utils.pickVersionedFile( format ) )
+			// Not used so far, but we'll need it.
+			// .pipe( utils.pickVersionedFile( format ) )
 			.pipe( babel( {
 				plugins: [ `transform-es2015-modules-${ babelModuleTranspiler }` ]
 			} ) );
 	},
 
+	/**
+	 * Creates a function adding transpilation pipes to the `pipes` param.
+	 * Used to generate `formats.reduce()` callback where `formats` is an array
+	 * of formats that should be generated.
+	 *
+	 * @param {String} distDir The `dist/` directory path.
+	 * @returns {Function}
+	 */
 	addFormat( distDir ) {
 		return ( pipes, format ) => {
 			const conversionPipes = [];
@@ -74,6 +104,11 @@ const utils = {
 		};
 	},
 
+	// Not used so far, but will allow us to pick one of files suffixed with the format (`__esnext`, `__amd`, or `__cjs`).
+	// This will be needed when we'll want to have different piece of code for specific formats.
+	//
+	// For example: we'll have `loader__esnext.js`, `loader__amd.js` and `loader__cjs.js`. After applying this
+	// transformation when compiling code for a specific format the proper file will be renamed to `loader.js`.
 	pickVersionedFile( format ) {
 		return rename( ( path ) => {
 			const regexp = new RegExp( `__${ format }$` );
@@ -83,8 +118,9 @@ const utils = {
 	},
 
 	/**
-	 * Move files out of `node_modules/ckeditor5-xxx/src/*` directories to `ckeditor5-xxx/*`.
+	 * Moves files out of `node_modules/ckeditor5-xxx/src/*` directories to `ckeditor5-xxx/*`.
 	 *
+	 * @param {RegExp} modulePathPattern
 	 * @returns {Stream}
 	 */
 	unpackModules( modulePathPattern ) {
@@ -98,6 +134,11 @@ const utils = {
 		} );
 	},
 
+	/**
+	 * Adds `ckeditor5/` to a file path.
+	 *
+	 * @returns {Stream}
+	 */
 	wrapCKEditor5Module() {
 		return rename( ( filePath ) => {
 			filePath.dirname = path.join( filePath.dirname, 'ckeditor5' );