Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Eslint JSDoc package, introducing JSDoc line alignment check #25300

Merged
merged 7 commits into from
Jun 9, 2021
Merged

Update Eslint JSDoc package, introducing JSDoc line alignment check #25300

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
7da65c9
Update eslint jsdoc dependency
renatho May 10, 2021
b7047df
Add Eslint check-line-alignment rule for JSDoc validations
renatho May 10, 2021
bbaebe3
Disable new rule after plugin update
renatho May 10, 2021
44c45a5
Remove return alignments (manually)
renatho May 13, 2021
db4fa5a
Update type of typeAnnotation param to a typedef
renatho May 21, 2021
5429bbf
Add changelog entry about jsdoc alignment
renatho May 21, 2021
7406b15
Fix jsdoc alignments
renatho Jun 8, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
12 changes: 7 additions & 5 deletions bin/packages/build-worker.js
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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