Skip to content

Commit

Permalink
Update Eslint JSDoc package, introducing JSDoc line alignment check (#…
Browse files Browse the repository at this point in the history 
…25300)

* Update eslint jsdoc dependency

* Add Eslint check-line-alignment rule for JSDoc validations

* Disable new rule after plugin update

It's temporarily disabled to allow the eslint plugin update
without errors.

* Remove return alignments (manually)

* Update type of typeAnnotation param to a typedef

The purpose of this change was readability improvement only.

* Add changelog entry about jsdoc alignment

* Fix jsdoc alignments

Co-authored-by: Renatho De Carli Rosa <[email protected]>
  • Loading branch information
@renatho
renatho and renatho authored Jun 9, 2021
1 parent efc28f9 commit a7e2895
Show file tree
Hide file tree
Showing 345 changed files with 1,741 additions and 1,594 deletions.
12 changes: 7 additions & 5 deletions bin/packages/build-worker.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,9 @@ const renderSass = promisify( sass.render );
/**
* Get the package name for a specified file
*
* @param {string} file File name
* @return {string} Package name
* @param {string} file File name.
*
* @return {string} Package name.
*/
function getPackageName( file ) {
return path.relative( PACKAGES_DIR, file ).split( path.sep )[ 0 ];
Expand All @@ -64,9 +65,10 @@ function getPackageName( file ) {
/**
* Get Build Path for a specified file.
*
* @param {string} file File to build
* @param {string} buildFolder Output folder
* @return {string} Build path
* @param {string} file File to build.
* @param {string} buildFolder Output folder.
*
* @return {string} Build path.
*/
function getBuildPath( file, buildFolder ) {
const pkgName = getPackageName( file );
Expand Down
15 changes: 9 additions & 6 deletions bin/packages/build.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,9 @@ const stylesheetEntryPoints = glob.sync(
/**
* Get the package name for a specified file
*
* @param {string} file File name
* @return {string} Package name
* @param {string} file File name.
*
* @return {string} Package name.
*/
function getPackageName( file ) {
return path.relative( PACKAGES_DIR, file ).split( path.sep )[ 0 ];
Expand All @@ -34,8 +35,9 @@ function getPackageName( file ) {
/**
* Parses all Sass import statements in a given file
*
* @param {string} file File name
* @return {Array} List of Import Statements in a file
* @param {string} file File name.
*
* @return {Array} List of Import Statements in a file.
*/
function parseImportStatements( file ) {
const fileContent = fs.readFileSync( file, 'utf8' );
Expand All @@ -58,8 +60,9 @@ function isFileImportedInStyleEntry( file, importStatements ) {
* Finds all stylesheet entry points that contain import statements
* that include the given file name
*
* @param {string} file File name
* @return {Array} List of entry points that import the styles from the file
* @param {string} file File name.
*
* @return {Array} List of entry points that import the styles from the file.
*/
function findStyleEntriesThatImportFile( file ) {
const entriesWithImport = stylesheetEntryPoints.reduce(
Expand Down
8 changes: 4 additions & 4 deletions bin/packages/watch.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -125,8 +125,8 @@ function getBuildFile( srcFile ) {
/**
* Adds a build file to the set of files that should be rebuilt.
*
* @param {'update'} event The event name
* @param {string} filename
* @param {'update'} event The event name
* @param {string} filename
*/
function updateBuildFile( event, filename ) {
if ( exists( filename ) ) {
Expand All @@ -147,8 +147,8 @@ function updateBuildFile( event, filename ) {
* Removes a build file from the build folder
* (usually triggered the associated source file was deleted)
*
* @param {'remove'} event The event name
* @param {string} filename
* @param {'remove'} event The event name
* @param {string} filename
*/
function removeBuildFile( event, filename ) {
const buildFile = getBuildFile( filename );
Expand Down
24 changes: 12 additions & 12 deletions bin/plugin/commands/changelog.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,19 +27,19 @@ const manifest = require( '../../../package.json' );
/**
* @typedef WPChangelogCommandOptions
*
* @property {string=} milestone Optional Milestone title.
* @property {string=} token Optional personal access token.
* @property {boolean=} unreleased Optional flag to only include issues that haven't been part of a release yet.
* @property {string=} milestone Optional Milestone title.
* @property {string=} token Optional personal access token.
* @property {boolean=} unreleased Optional flag to only include issues that haven't been part of a release yet.
*/

/**
* @typedef WPChangelogSettings
*
* @property {string} owner Repository owner.
* @property {string} repo Repository name.
* @property {string=} token Optional personal access token.
* @property {string} milestone Milestone title.
* @property {boolean=} unreleased Only include issues that have been closed since the milestone's latest release.
* @property {string} owner Repository owner.
* @property {string} repo Repository name.
* @property {string=} token Optional personal access token.
* @property {string} milestone Milestone title.
* @property {boolean=} unreleased Only include issues that have been closed since the milestone's latest release.
*/

/**
Expand Down Expand Up @@ -386,10 +386,10 @@ function getEntry( issue ) {
/**
* Returns the latest release for a given series
*
* @param {GitHub} octokit Initialized Octokit REST client.
* @param {string} owner Repository owner.
* @param {string} repo Repository name.
* @param {string} series Gutenberg release series (e.g. '6.7' or '9.8').
* @param {GitHub} octokit Initialized Octokit REST client.
* @param {string} owner Repository owner.
* @param {string} repo Repository name.
* @param {string} series Gutenberg release series (e.g. '6.7' or '9.8').
*
* @return {Promise<ReposListReleasesResponseItem|undefined>} Promise resolving to pull
* requests for the given
Expand Down
2 changes: 1 addition & 1 deletion bin/plugin/commands/common.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@ function findReleaseBranchName( packageJsonPath ) {
* Calculates version bump for the packages based on the content
* from the provided CHANGELOG file split into individual lines.
*
* @param {string[]} lines Changelog content split into lines.
* @param {string[]} lines Changelog content split into lines.
* @param {('patch'|'minor'|'major')} [minimumVersionBump] Minimum version bump for the package.
* Defaults to `patch`.
*
Expand Down
20 changes: 10 additions & 10 deletions bin/plugin/commands/packages.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,9 @@ const git = require( '../lib/git' );
* Checks out the WordPress release branch and syncs it with the changes from
* the last plugin release.
*
* @param {string} gitWorkingDirectoryPath Git working directory path.
* @param {boolean} isPrerelease Whether the package version to publish is a prerelease.
* @param {string} abortMessage Abort Message.
* @param {string} gitWorkingDirectoryPath Git working directory path.
* @param {boolean} isPrerelease Whether the package version to publish is a prerelease.
* @param {string} abortMessage Abort Message.
*
* @return {Promise<Object>} WordPress release branch.
*/
Expand Down Expand Up @@ -97,10 +97,10 @@ async function runWordPressReleaseBranchSyncStep(
* Update CHANGELOG files with the new version number for those packages that
* contain new entries.
*
* @param {string} gitWorkingDirectoryPath Git working directory path.
* @param {SemVer} minimumVersionBump Minimum version bump for the packages.
* @param {boolean} isPrerelease Whether the package version to publish is a prerelease.
* @param {string} abortMessage Abort Message.
* @param {string} gitWorkingDirectoryPath Git working directory path.
* @param {SemVer} minimumVersionBump Minimum version bump for the packages.
* @param {boolean} isPrerelease Whether the package version to publish is a prerelease.
* @param {string} abortMessage Abort Message.
*/
async function updatePackages(
gitWorkingDirectoryPath,
Expand Down Expand Up @@ -274,9 +274,9 @@ async function runPushGitChangesStep(
/**
* Publishes all changed packages to npm.
*
* @param {string} gitWorkingDirectoryPath Git working directory path.
* @param {SemVer} minimumVersionBump Minimum version bump for the packages.
* @param {boolean} isPrerelease Whether the package version to publish is a prerelease.
* @param {string} gitWorkingDirectoryPath Git working directory path.
* @param {SemVer} minimumVersionBump Minimum version bump for the packages.
* @param {boolean} isPrerelease Whether the package version to publish is a prerelease.
*/
async function publishPackagesToNpm(
gitWorkingDirectoryPath,
Expand Down
68 changes: 34 additions & 34 deletions bin/plugin/commands/performance.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,46 +29,46 @@ const config = require( '../config' );
/**
* @typedef WPRawPerformanceResults
*
* @property {number[]} load Load Time.
* @property {number[]} type Average type time.
* @property {number[]} focus Average block selection time.
* @property {number[]} inserterOpen Average time to open global inserter.
* @property {number[]} inserterHover Average time to move mouse between two block item in the inserter.
* @property {number[]} load Load Time.
* @property {number[]} type Average type time.
* @property {number[]} focus Average block selection time.
* @property {number[]} inserterOpen Average time to open global inserter.
* @property {number[]} inserterHover Average time to move mouse between two block item in the inserter.
*/

/**
* @typedef WPPerformanceResults
*
* @property {number} load Load Time.
* @property {number} type Average type time.
* @property {number} minType Minium type time.
* @property {number} maxType Maximum type time.
* @property {number} focus Average block selection time.
* @property {number} minFocus Min block selection time.
* @property {number} maxFocus Max block selection time.
* @property {number} inserterOpen Average time to open global inserter.
* @property {number} minInserterOpen Min time to open global inserter.
* @property {number} maxInserterOpen Max time to open global inserter.
* @property {number} inserterHover Average time to move mouse between two block item in the inserter.
* @property {number} minInserterHover Min time to move mouse between two block item in the inserter.
* @property {number} maxInserterHover Max time to move mouse between two block item in the inserter.
* @property {number} load Load Time.
* @property {number} type Average type time.
* @property {number} minType Minium type time.
* @property {number} maxType Maximum type time.
* @property {number} focus Average block selection time.
* @property {number} minFocus Min block selection time.
* @property {number} maxFocus Max block selection time.
* @property {number} inserterOpen Average time to open global inserter.
* @property {number} minInserterOpen Min time to open global inserter.
* @property {number} maxInserterOpen Max time to open global inserter.
* @property {number} inserterHover Average time to move mouse between two block item in the inserter.
* @property {number} minInserterHover Min time to move mouse between two block item in the inserter.
* @property {number} maxInserterHover Max time to move mouse between two block item in the inserter.
*/
/**
* @typedef WPFormattedPerformanceResults
*
* @property {string=} load Load Time.
* @property {string=} type Average type time.
* @property {string=} minType Minium type time.
* @property {string=} maxType Maximum type time.
* @property {string=} focus Average block selection time.
* @property {string=} minFocus Min block selection time.
* @property {string=} maxFocus Max block selection time.
* @property {string=} inserterOpen Average time to open global inserter.
* @property {string=} minInserterOpen Min time to open global inserter.
* @property {string=} maxInserterOpen Max time to open global inserter.
* @property {string=} inserterHover Average time to move mouse between two block item in the inserter.
* @property {string=} minInserterHover Min time to move mouse between two block item in the inserter.
* @property {string=} maxInserterHover Max time to move mouse between two block item in the inserter.
* @property {string=} load Load Time.
* @property {string=} type Average type time.
* @property {string=} minType Minium type time.
* @property {string=} maxType Maximum type time.
* @property {string=} focus Average block selection time.
* @property {string=} minFocus Min block selection time.
* @property {string=} maxFocus Max block selection time.
* @property {string=} inserterOpen Average time to open global inserter.
* @property {string=} minInserterOpen Min time to open global inserter.
* @property {string=} maxInserterOpen Max time to open global inserter.
* @property {string=} inserterHover Average time to move mouse between two block item in the inserter.
* @property {string=} minInserterHover Min time to move mouse between two block item in the inserter.
* @property {string=} maxInserterHover Max time to move mouse between two block item in the inserter.
*/

/**
Expand Down Expand Up @@ -137,8 +137,8 @@ function curateResults( results ) {
/**
* Set up the given branch for testing.
*
* @param {string} branch Branch name.
* @param {string} environmentDirectory Path to the plugin environment's clone.
* @param {string} branch Branch name.
* @param {string} environmentDirectory Path to the plugin environment's clone.
*/
async function setUpGitBranch( branch, environmentDirectory ) {
// Restore clean working directory (e.g. if `package-lock.json` has local
Expand Down Expand Up @@ -208,7 +208,7 @@ async function runTestSuite( testSuite, performanceTestDirectory ) {
* Runs the performances tests on an array of branches and output the result.
*
* @param {string[]} branches Branches to compare
* @param {WPPerformanceCommandOptions} options Command options.
* @param {WPPerformanceCommandOptions} options Command options.
*/
async function runPerformanceTests( branches, options ) {
// The default value doesn't work because commander provides an array.
Expand Down
28 changes: 14 additions & 14 deletions bin/plugin/config.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,21 @@ const gitRepoOwner = 'WordPress';
/**
* @typedef WPPluginCLIConfig
*
* @property {string} slug Slug.
* @property {string} name Name.
* @property {string} team Github Team Name.
* @property {string} versionMilestoneFormat printf template for milestone
* version name. Expected to be called
* with a merged object of the config
* and semver-parsed version parts.
* @property {string} githubRepositoryOwner Github Repository Owner.
* @property {string} githubRepositoryName Github Repository Name.
* @property {string} pluginEntryPoint Plugin Entry Point File.
* @property {string} buildZipCommand Build Plugin ZIP command.
* @property {string} githubRepositoryURL GitHub Repository URL.
* @property {string} slug Slug.
* @property {string} name Name.
* @property {string} team Github Team Name.
* @property {string} versionMilestoneFormat printf template for milestone
* version name. Expected to be called
* with a merged object of the config
* and semver-parsed version parts.
* @property {string} githubRepositoryOwner Github Repository Owner.
* @property {string} githubRepositoryName Github Repository Name.
* @property {string} pluginEntryPoint Plugin Entry Point File.
* @property {string} buildZipCommand Build Plugin ZIP command.
* @property {string} githubRepositoryURL GitHub Repository URL.
* @property {string} wpRepositoryReleasesURL WordPress Repository Tags URL.
* @property {string} gitRepositoryURL Git Repository URL.
* @property {string} svnRepositoryURL SVN Repository URL.
* @property {string} gitRepositoryURL Git Repository URL.
* @property {string} svnRepositoryURL SVN Repository URL.
*/

/**
Expand Down
20 changes: 10 additions & 10 deletions bin/plugin/lib/git.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,9 @@ async function clone( repositoryUrl ) {
/**
* Commits changes to the repository.
*
* @param {string} gitWorkingDirectoryPath Local repository path.
* @param {string} message Commit message.
* @param {string[]} filesToAdd Files to add.
* @param {string} gitWorkingDirectoryPath Local repository path.
* @param {string} message Commit message.
* @param {string[]} filesToAdd Files to add.
*
* @return {Promise<string>} Commit Hash
*/
Expand All @@ -48,7 +48,7 @@ async function commit( gitWorkingDirectoryPath, message, filesToAdd = [] ) {
* Creates a local branch.
*
* @param {string} gitWorkingDirectoryPath Local repository path.
* @param {string} branchName Branch Name
* @param {string} branchName Branch Name
*/
async function createLocalBranch( gitWorkingDirectoryPath, branchName ) {
const simpleGit = SimpleGit( gitWorkingDirectoryPath );
Expand All @@ -59,7 +59,7 @@ async function createLocalBranch( gitWorkingDirectoryPath, branchName ) {
* Checkout a local branch.
*
* @param {string} gitWorkingDirectoryPath Local repository path.
* @param {string} branchName Branch Name
* @param {string} branchName Branch Name
*/
async function checkoutRemoteBranch( gitWorkingDirectoryPath, branchName ) {
const simpleGit = SimpleGit( gitWorkingDirectoryPath );
Expand All @@ -71,7 +71,7 @@ async function checkoutRemoteBranch( gitWorkingDirectoryPath, branchName ) {
* Creates a local tag.
*
* @param {string} gitWorkingDirectoryPath Local repository path.
* @param {string} tagName Tag Name
* @param {string} tagName Tag Name
*/
async function createLocalTag( gitWorkingDirectoryPath, tagName ) {
const simpleGit = SimpleGit( gitWorkingDirectoryPath );
Expand All @@ -82,7 +82,7 @@ async function createLocalTag( gitWorkingDirectoryPath, tagName ) {
* Pushes a local branch to the origin.
*
* @param {string} gitWorkingDirectoryPath Local repository path.
* @param {string} branchName Branch Name
* @param {string} branchName Branch Name
*/
async function pushBranchToOrigin( gitWorkingDirectoryPath, branchName ) {
const simpleGit = SimpleGit( gitWorkingDirectoryPath );
Expand Down Expand Up @@ -113,7 +113,7 @@ async function discardLocalChanges( gitWorkingDirectoryPath ) {
* Reset local branch against the origin.
*
* @param {string} gitWorkingDirectoryPath Local repository path.
* @param {string} branchName Branch Name
* @param {string} branchName Branch Name
*/
async function resetLocalBranchAgainstOrigin(
gitWorkingDirectoryPath,
Expand All @@ -129,7 +129,7 @@ async function resetLocalBranchAgainstOrigin(
* Cherry-picks a commit into trunk
*
* @param {string} gitWorkingDirectoryPath Local repository path.
* @param {string} commitHash Branch Name
* @param {string} commitHash Branch Name
*/
async function cherrypickCommitIntoBranch(
gitWorkingDirectoryPath,
Expand All @@ -144,7 +144,7 @@ async function cherrypickCommitIntoBranch(
* Replaces the local branch's content with the content from another branch.
*
* @param {string} gitWorkingDirectoryPath Local repository path.
* @param {string} sourceBranchName Branch Name
* @param {string} sourceBranchName Branch Name
*/
async function replaceContentFromRemoteBranch(
gitWorkingDirectoryPath,
Expand Down
Loading

0 comments on commit a7e2895

Please sign in to comment.