8
0
Просмотр исходного кода

API docs improvements and small refactoring.

Piotrek Koszuliński 9 лет назад
Родитель
Сommit
cbf1054e14

+ 1 - 1
dev/tasks/build/utils.js

@@ -534,7 +534,7 @@ require( [ 'tests' ], bender.defer(), function( err ) {
 	},
 	},
 
 
 	/**
 	/**
-	 * Given a stream of .svg files it returns a stream containing JavaScript
+	 * Given a stream of `.svg` files it returns a stream containing JavaScript
 	 * icon sprite file.
 	 * icon sprite file.
 	 *
 	 *
 	 * @returns {Stream}
 	 * @returns {Stream}

+ 9 - 5
dev/tasks/exec/functions/bump-year.js

@@ -10,16 +10,20 @@ const path = require( 'path' );
 const replace = require( 'gulp-replace' );
 const replace = require( 'gulp-replace' );
 const filterGitignore = require( '../utils/filtergitignore' );
 const filterGitignore = require( '../utils/filtergitignore' );
 
 
+// Change this to correct year.
+const year = '2017';
+
 /**
 /**
  * Replaces license date in source files with new date.
  * Replaces license date in source files with new date.
  *
  *
+ * Example (remember to change the year harcoded in the module):
+ *
+ *		gulp exec --task bump-year
+ *
  * @param {String} workdir
  * @param {String} workdir
- * @returns {Object} stream
+ * @returns {Object}
  */
  */
-module.exports = ( workdir ) => {
-	// Change this to correct year.
-	const year = '2017';
-
+module.exports = function executeBumpYear( workdir ) {
 	const licenseRegexp = /(@license Copyright \(c\) 2003-)[0-9]{4}(, CKSource - Frederico Knabben\.)/g;
 	const licenseRegexp = /(@license Copyright \(c\) 2003-)[0-9]{4}(, CKSource - Frederico Knabben\.)/g;
 	const glob = path.join( workdir, '**/*' );
 	const glob = path.join( workdir, '**/*' );
 
 

+ 3 - 3
dev/tasks/exec/functions/git-commit.js

@@ -12,14 +12,14 @@ const PassThrough = require( 'stream' ).PassThrough;
  * Adds only modified files to git repository and commits them with provided message.
  * Adds only modified files to git repository and commits them with provided message.
  *
  *
  * Example:
  * Example:
-
+ *
  *		gulp exec --task git-commit --message "Commit message."
  *		gulp exec --task git-commit --message "Commit message."
  *
  *
  * @param {String} workdir
  * @param {String} workdir
  * @param {Object} params
  * @param {Object} params
- * @returns {Stream} stream
+ * @returns {Stream}
  */
  */
-module.exports = ( workdir, params ) => {
+module.exports = function executeGitCommit( workdir, params ) {
 	const message = params.message;
 	const message = params.message;
 
 
 	if ( !message ) {
 	if ( !message ) {

+ 6 - 2
dev/tasks/exec/functions/git-push.js

@@ -11,10 +11,14 @@ const PassThrough = require( 'stream' ).PassThrough;
 /**
 /**
  * Pushes changes of current branch in repository to default origin.
  * Pushes changes of current branch in repository to default origin.
  *
  *
+ * Example:
+ *
+ *		gulp exec --task git-push
+ *
  * @param {String} workdir
  * @param {String} workdir
- * @returns {Object} stream
+ * @returns {Stream}
  */
  */
-module.exports = ( workdir ) => {
+module.exports = function executeGitPush( workdir ) {
 	git.push( workdir );
 	git.push( workdir );
 
 
 	// Return dummy stream to inform gulp about finishing task.
 	// Return dummy stream to inform gulp about finishing task.

+ 21 - 17
dev/tasks/exec/tasks.js

@@ -13,14 +13,14 @@ const log = require( '../../utils/log' );
 const ckeditor5Dirs = require( '../../utils/ckeditor5-dirs' );
 const ckeditor5Dirs = require( '../../utils/ckeditor5-dirs' );
 
 
 /**
 /**
- * Run task over ckeditor5 repositories.
+ * Run task over `ckeditor5-*` repositories.
  *
  *
  * Example:
  * Example:
-
+ *
  *		gulp exec --task task-name
  *		gulp exec --task task-name
  *
  *
  * Example of running task just for one repository:
  * Example of running task just for one repository:
-
+ *
  *		gulp exec --task task-name --repository ckeditor5-utils
  *		gulp exec --task task-name --repository ckeditor5-utils
  *
  *
  * @param {Object} config Task runner configuration.
  * @param {Object} config Task runner configuration.
@@ -29,25 +29,28 @@ const ckeditor5Dirs = require( '../../utils/ckeditor5-dirs' );
 module.exports = ( config ) => {
 module.exports = ( config ) => {
 	const ckeditor5Path = process.cwd();
 	const ckeditor5Path = process.cwd();
 	const packageJSON = require( '../../../package.json' );
 	const packageJSON = require( '../../../package.json' );
+
 	const tasks = {
 	const tasks = {
 		execOnRepositories() {
 		execOnRepositories() {
 			// Omit `gulp exec` part of arguments
 			// Omit `gulp exec` part of arguments
-			const parameters = minimist( process.argv.slice( 3 ), {
+			const params = minimist( process.argv.slice( 3 ), {
 				stopEarly: false,
 				stopEarly: false,
 			} );
 			} );
 			let task;
 			let task;
 
 
 			try {
 			try {
-				if ( parameters.task ) {
-					task = require( `./functions/${ parameters.task }` );
+				if ( params.task ) {
+					task = require( `./functions/${ params.task }` );
 				} else {
 				} else {
 					throw new Error( 'Missing task parameter: --task task-name' );
 					throw new Error( 'Missing task parameter: --task task-name' );
 				}
 				}
-			} catch ( error ) {
-				log.err( error );
+			} catch ( err ) {
+				log.err( err );
+
+				return;
 			}
 			}
 
 
-			return execute( task, ckeditor5Path, packageJSON, config.WORKSPACE_DIR, parameters );
+			return execute( task, ckeditor5Path, packageJSON, config.WORKSPACE_DIR, params );
 		},
 		},
 
 
 		register() {
 		register() {
@@ -63,15 +66,15 @@ module.exports = ( config ) => {
  *
  *
  * @param {Function} execTask Task to use on each dependency.
  * @param {Function} execTask Task to use on each dependency.
  * @param {String} ckeditor5Path Path to main CKEditor5 repository.
  * @param {String} ckeditor5Path Path to main CKEditor5 repository.
- * @param {Object} packageJSON Parsed package.json file from CKEditor5 repository.
+ * @param {Object} packageJSON Parsed `package.json` file from CKEditor 5 repository.
  * @param {String} workspaceRoot Relative path to workspace root.
  * @param {String} workspaceRoot Relative path to workspace root.
- * @param {Object} parameters Parameters provided to the task via command-line.
+ * @param {Object} params Parameters provided to the task via command-line.
  * @returns {Stream} Merged stream of processed files.
  * @returns {Stream} Merged stream of processed files.
  */
  */
-function execute( execTask, ckeditor5Path, packageJSON, workspaceRoot, parameters ) {
+function execute( execTask, ckeditor5Path, packageJSON, workspaceRoot, params ) {
 	const workspacePath = path.join( ckeditor5Path, workspaceRoot );
 	const workspacePath = path.join( ckeditor5Path, workspaceRoot );
 	const mergedStream = merge();
 	const mergedStream = merge();
-	const specificRepository = parameters.repository;
+	const specificRepository = params.repository;
 
 
 	let devDirectories = ckeditor5Dirs.getDevDirectories( workspacePath, packageJSON, ckeditor5Path );
 	let devDirectories = ckeditor5Dirs.getDevDirectories( workspacePath, packageJSON, ckeditor5Path );
 
 
@@ -81,12 +84,13 @@ function execute( execTask, ckeditor5Path, packageJSON, workspaceRoot, parameter
 		} );
 		} );
 	}
 	}
 
 
-	for ( let dir of devDirectories ) {
+	for ( const dir of devDirectories ) {
 		try {
 		try {
 			log.out( `Executing task on ${ dir.repositoryURL }...` );
 			log.out( `Executing task on ${ dir.repositoryURL }...` );
-			mergedStream.add( execTask( dir.repositoryPath, parameters ) );
-		} catch ( error ) {
-			log.err( error );
+
+			mergedStream.add( execTask( dir.repositoryPath, params ) );
+		} catch ( err ) {
+			log.err( err );
 		}
 		}
 	}
 	}
 
 

+ 8 - 8
dev/tasks/exec/utils/filtergitignore.js

@@ -11,17 +11,17 @@ const parseGitignore = require( 'parse-gitignore' );
 const PassThrough = require( 'stream' ).PassThrough;
 const PassThrough = require( 'stream' ).PassThrough;
 
 
 module.exports = function filterGitignore() {
 module.exports = function filterGitignore() {
-	const fp = '.gitignore';
+	const fileName = '.gitignore';
 
 
-	if ( !fs.existsSync( fp ) ) {
+	if ( !fs.existsSync( fileName ) ) {
 		return new PassThrough( { objectMode: true } );
 		return new PassThrough( { objectMode: true } );
 	}
 	}
 
 
-	const glob = parseGitignore( fp );
-	const inverted = glob.map(
-		pattern => pattern.startsWith( '!' ) ? pattern.slice( 1 ) : '!' + pattern
-	);
-	inverted.unshift( '**/*' );
+	const gitignoreGlob =
+		parseGitignore( fileName )
+			// Invert '!foo' -> 'foo' and 'foo' -> '!foo'.
+			.map( pattern => pattern.startsWith( '!' ) ? pattern.slice( 1 ) : '!' + pattern )
+			.unshift( '**/*' );
 
 
-	return filter( inverted );
+	return filter( gitignoreGlob );
 };
 };

+ 8 - 9
dev/utils/ckeditor5-dirs.js

@@ -12,19 +12,18 @@ const git = require( './git' );
 const dependencyRegExp = /^ckeditor5-/;
 const dependencyRegExp = /^ckeditor5-/;
 
 
 module.exports = {
 module.exports = {
-
 	/**
 	/**
-	 * Returns dependencies that starts with ckeditor5-, and have valid, short GitHub url. Returns null if no
+	 * Returns dependencies that starts with `ckeditor5-`, and have valid, short GitHub url. Returns `null` if no
 	 * dependencies are found.
 	 * dependencies are found.
 	 *
 	 *
-	 * @param {Object} dependencies Dependencies object loaded from package.json file.
+	 * @param {Object} dependencies Dependencies object loaded from `package.json` file.
 	 * @returns {Object|null}
 	 * @returns {Object|null}
 	 */
 	 */
 	getDependencies( dependencies ) {
 	getDependencies( dependencies ) {
 		let result = null;
 		let result = null;
 
 
 		if ( dependencies ) {
 		if ( dependencies ) {
-			Object.keys( dependencies ).forEach( function( key ) {
+			Object.keys( dependencies ).forEach( ( key ) => {
 				if ( dependencyRegExp.test( key ) ) {
 				if ( dependencyRegExp.test( key ) ) {
 					if ( result === null ) {
 					if ( result === null ) {
 						result = {};
 						result = {};
@@ -39,10 +38,10 @@ module.exports = {
 	},
 	},
 
 
 	/**
 	/**
-	 * Returns all directories under specified path that match 'ckeditor5' pattern.
+	 * Returns all directories under specified path that match `ckeditor5-*` pattern.
 	 *
 	 *
 	 * @param {String} path
 	 * @param {String} path
-	 * @returns {Array}
+	 * @returns {Array.<String>}
 	 */
 	 */
 	getDirectories( path ) {
 	getDirectories( path ) {
 		return tools.getDirectories( path ).filter( dir => {
 		return tools.getDirectories( path ).filter( dir => {
@@ -51,7 +50,7 @@ module.exports = {
 	},
 	},
 
 
 	/**
 	/**
-	 * Returns list of symbolic links to directories with names starting with `ckeditor5-` prefix.
+	 * Returns a list of symbolic links to directories with names starting with `ckeditor5-` prefix.
 	 *
 	 *
 	 * @param {String} path Path to directory,
 	 * @param {String} path Path to directory,
 	 * @returns {Array} Array with directories names.
 	 * @returns {Array} Array with directories names.
@@ -68,10 +67,10 @@ module.exports = {
 	},
 	},
 
 
 	/**
 	/**
-	 * Returns array with information about ckeditor5-* directories in development mode.
+	 * Returns an array with information about `ckeditor5-*` directories in development mode.
 	 *
 	 *
 	 * @param {String} workspacePath Absolute path to workspace.
 	 * @param {String} workspacePath Absolute path to workspace.
-	 * @param {Object} packageJSON Contents of ckeditor5 repo package.json file.
+	 * @param {Object} packageJSON Contents of `ckeditor5` repo `package.json` file.
 	 * @param {String} ckeditor5Path Absolute path to ckeditor5 root directory.
 	 * @param {String} ckeditor5Path Absolute path to ckeditor5 root directory.
 	 * @returns {Array.<Object>}
 	 * @returns {Array.<Object>}
 	 */
 	 */

+ 0 - 1
dev/utils/git.js

@@ -9,7 +9,6 @@ const tools = require( './tools' );
 const defaultOrigin = 'origin';
 const defaultOrigin = 'origin';
 
 
 module.exports = {
 module.exports = {
-
 	/**
 	/**
 	 * Parses GitHub URL. Extracts used server, repository and branch.
 	 * Parses GitHub URL. Extracts used server, repository and branch.
 	 *
 	 *

+ 0 - 1
dev/utils/tools.js

@@ -8,7 +8,6 @@
 const gutil = require( 'gulp-util' );
 const gutil = require( 'gulp-util' );
 
 
 module.exports = {
 module.exports = {
-
 	/**
 	/**
 	 * Executes a shell command.
 	 * Executes a shell command.
 	 *
 	 *