@wordpress/env: Make JSDoc conform to coding guidelines

packages/env/lib/build-docker-compose-config.js

@@ -6,14 +6,15 @@ const fs = require( 'fs' );
 const path = require( 'path' );
 
 /**
- * @typedef {import('./config').Config} Config
+ * @typedef {import('./config').WPConfig} WPConfig
  */
 
 /**
  * Creates a docker-compose config object which, when serialized into a
  * docker-compose.yml file, tells docker-compose how to run the environment.
  *
- * @param {Config} config A wp-env config object.
+ * @param {WPConfig} config A wp-env config object.
+ *
  * @return {Object} A docker-compose config object, ready to serialize into YAML.
  */
 module.exports = function buildDockerComposeConfig( config ) {

packages/env/lib/commands/clean.js

@@ -4,13 +4,18 @@
 const initConfig = require( '../init-config' );
 const { configureWordPress, resetDatabase } = require( '../wordpress' );
 
+/**
+ * @typedef {import('../wordpress').WPEnvironment} WPEnvironment
+ * @typedef {import('../wordpress').WPEnvironmentSelection} WPEnvironmentSelection
+ */
+
 /**
  * Wipes the development server's database, the tests server's database, or both.
  *
- * @param {Object}  options
- * @param {string}  options.environment The environment to clean. Either 'development', 'tests', or 'all'.
- * @param {Object}  options.spinner     A CLI spinner which indicates progress.
- * @param {boolean} options.debug       True if debug mode is enabled.
+ * @param {Object}                 options
+ * @param {WPEnvironmentSelection} options.environment The environment to clean. Either 'development', 'tests', or 'all'.
+ * @param {Object}                 options.spinner     A CLI spinner which indicates progress.
+ * @param {boolean}                options.debug       True if debug mode is enabled.
  */
 module.exports = async function clean( { environment, spinner, debug } ) {
 	const config = await initConfig( { spinner, debug } );

packages/env/lib/config.js

@@ -27,14 +27,14 @@ const HOME_PATH_PREFIX = `~${ path.sep }`;
 /**
  * A wp-env config object.
  *
- * @typedef Config
+ * @typedef WPConfig
  * @property {string}      name                    Name of the environment.
  * @property {string}      configDirectoryPath     Path to the .wp-env.json file.
  * @property {string}      workDirectoryPath       Path to the work directory located in ~/.wp-env.
  * @property {string}      dockerComposeConfigPath Path to the docker-compose.yml file.
- * @property {Source|null} coreSource              The WordPress installation to load in the environment.
- * @property {Source[]}    pluginSources           Plugins to load in the environment.
- * @property {Source[]}    themeSources            Themes to load in the environment.
+ * @property {?WPSource}   coreSource              The WordPress installation to load in the environment.
+ * @property {WPSource[]}  pluginSources           Plugins to load in the environment.
+ * @property {WPSource[]}  themeSources            Themes to load in the environment.
  * @property {number}      port                    The port on which to start the development WordPress environment.
  * @property {number}      testsPort               The port on which to start the testing WordPress environment.
  * @property {Object}      config                  Mapping of wp-config.php constants to their desired values.
@@ -44,7 +44,7 @@ const HOME_PATH_PREFIX = `~${ path.sep }`;
 /**
  * A WordPress installation, plugin or theme to be loaded into the environment.
  *
- * @typedef Source
+ * @typedef WPSource
  * @property {string} type The source type. Can be 'local' or 'git'.
  * @property {string} path The path to the WordPress installation, plugin or theme.
  * @property {string} basename Name that identifies the WordPress installation, plugin or theme.
@@ -57,7 +57,8 @@ module.exports = {
 	 * Reads and parses the given .wp-env.json file into a wp-env config object.
 	 *
 	 * @param {string} configPath Path to the .wp-env.json file.
-	 * @return {Config} A wp-env config object.
+	 *
+	 * @return {WPConfig} A wp-env config object.
 	 */
 	async readConfig( configPath ) {
 		const configDirectoryPath = path.dirname( configPath );
@@ -224,11 +225,12 @@ module.exports = {
 /**
  * Parses a source string into a source object.
  *
- * @param {string|null} sourceString The source string. See README.md for documentation on valid source string patterns.
+ * @param {?string} sourceString The source string. See README.md for documentation on valid source string patterns.
  * @param {Object} options
  * @param {boolean} options.hasTests Whether or not a `testsPath` is required. Only the 'core' source needs this.
  * @param {string} options.workDirectoryPath Path to the work directory located in ~/.wp-env.
- * @return {Source|null} A source object.
+ *
+ * @return {?WPSource} A source object.
  */
 function parseSourceString( sourceString, { workDirectoryPath } ) {
 	if ( sourceString === null ) {
@@ -292,10 +294,11 @@ function parseSourceString( sourceString, { workDirectoryPath } ) {
  * Given a source object, returns a new source object with the testsPath
  * property set correctly. Only the 'core' source requires a testsPath.
  *
- * @param {Source|null} source A source object.
- * @param {Object} options
- * @param {string} options.workDirectoryPath Path to the work directory located in ~/.wp-env.
- * @return {Source|null} A source object.
+ * @param {?WPSource} source                    A source object.
+ * @param {Object}  options
+ * @param {string}  options.workDirectoryPath Path to the work directory located in ~/.wp-env.
+ *
+ * @return {?WPSource} A source object.
  */
 function includeTestsPath( source, { workDirectoryPath } ) {
 	if ( source === null ) {

packages/env/lib/download-source.js

@@ -17,14 +17,14 @@ const rimraf = util.promisify( require( 'rimraf' ) );
 const copyDir = util.promisify( require( 'copy-dir' ) );
 
 /**
- * @typedef {import('./config').Source} Source
+ * @typedef {import('./config').WPSource} WPSource
  */
 
 /**
  * Downloads the given source if necessary. The specific action taken depends
  * on the source type.
  *
- * @param {Source}   source             The source to download.
+ * @param {WPSource} source             The source to download.
  * @param {Object}   options
  * @param {Function} options.onProgress A function called with download progress. Will be invoked with one argument: a number that ranges from 0 to 1 which indicates current download progress for this source.
  * @param {Object}   options.spinner    A CLI spinner which indicates progress.
@@ -42,7 +42,7 @@ module.exports = async function downloadSource( source, options ) {
  * Clones the git repository at `source.url` into `source.path`. If the
  * repository already exists, it is updated instead.
  *
- * @param {Source}   source             The source to download.
+ * @param {WPSource} source             The source to download.
  * @param {Object}   options
  * @param {Function} options.onProgress A function called with download progress. Will be invoked with one argument: a number that ranges from 0 to 1 which indicates current download progress for this source.
  * @param {Object}   options.spinner    A CLI spinner which indicates progress.
@@ -113,7 +113,7 @@ async function downloadGitSource( source, { onProgress, spinner, debug } ) {
 /**
  * Downloads and extracts the zip file at `source.url` into `source.path`.
  *
- * @param {Source}   source             The source to download.
+ * @param {WPSource} source             The source to download.
  * @param {Object}   options
  * @param {Function} options.onProgress A function called with download progress. Will be invoked with one argument: a number that ranges from 0 to 1 which indicates current download progress for this source.
  * @param {Object}   options.spinner    A CLI spinner which indicates progress.

packages/env/lib/init-config.js

@@ -12,18 +12,18 @@ const { readConfig } = require( './config' );
 const buildDockerComposeConfig = require( './build-docker-compose-config' );
 
 /**
- * @typedef {import('./config').Config} Config
+ * @typedef {import('./config').WPConfig} WPConfig
  */
 
 /**
  * Initializes the local environment so that Docker commands can be run. Reads
  * ./.wp-env.json, creates ~/.wp-env, and creates ~/.wp-env/docker-compose.yml.
  *
  * @param {Object}  options
- * @param {Object}  options.spinner initConfigA CLI spinner which indicates progress.
+ * @param {Object}  options.spinner A CLI spinner which indicates progress.
  * @param {boolean} options.debug   True if debug mode is enabled.
  *
- * @return {Config} The-env config object.
+ * @return {WPConfig} The-env config object.
  */
 module.exports = async function initConfig( { spinner, debug } ) {
 	const configPath = path.resolve( '.wp-env.json' );

packages/env/lib/wordpress.js

@@ -10,7 +10,9 @@ const util = require( 'util' );
 const copyDir = util.promisify( require( 'copy-dir' ) );
 
 /**
- * @typedef {import('./config').Config} Config
+ * @typedef {import('./config').WPConfig} WPConfig
+ * @typedef {'development'|'tests'} WPEnvironment
+ * @typedef {'development'|'tests'|'all'} WPEnvironmentSelection
  */
 
 /**
@@ -25,8 +27,8 @@ const copyDir = util.promisify( require( 'copy-dir' ) );
  *
  * See https://github.com/docker-library/wordpress/issues/436.
  *
- * @param {string} environment The environment to check. Either 'development' or 'tests'.
- * @param {Config} config The wp-env config object.
+ * @param {WPEnvironment} environment The environment to check. Either 'development' or 'tests'.
+ * @param {WPConfig}      config      The wp-env config object.
  */
 async function makeContentDirectoriesWritable(
 	environment,
@@ -46,7 +48,7 @@ async function makeContentDirectoriesWritable(
  * Checks a WordPress database connection. An error is thrown if the test is
  * unsuccessful.
  *
- * @param {Config} config The wp-env config object.
+ * @param {WPConfig} config The wp-env config object.
  */
 async function checkDatabaseConnection( { dockerComposeConfigPath, debug } ) {
 	await dockerCompose.run( 'cli', 'wp db check', {
@@ -61,8 +63,8 @@ async function checkDatabaseConnection( { dockerComposeConfigPath, debug } ) {
  * activating all plugins, and activating the first theme. These steps are
  * performed sequentially so as to not overload the WordPress instance.
  *
- * @param {string} environment The environment to configure. Either 'development' or 'tests'.
- * @param {Config} config The wp-env config object.
+ * @param {WPEnvironment} environment The environment to configure. Either 'development' or 'tests'.
+ * @param {WPConfig}      config      The wp-env config object.
  */
 async function configureWordPress( environment, config ) {
 	const options = {
@@ -126,8 +128,8 @@ async function configureWordPress( environment, config ) {
 /**
  * Resets the development server's database, the tests server's database, or both.
  *
- * @param {string} environment The environment to clean. Either 'development', 'tests', or 'all'.
- * @param {Config} config The wp-env config object.
+ * @param {WPEnvironmentSelection} environment The environment to clean. Either 'development', 'tests', or 'all'.
+ * @param {WPConfig}               config      The wp-env config object.
  */
 async function resetDatabase(
 	environment,