Skip to content

Commit c385ad9

Browse files
pgonzalpgonzal
committed
Update doc comments for various projects to be compatible with the new TSDoc syntaxes
1 parent 847a75c commit c385ad9

12 files changed

Lines changed: 51 additions & 53 deletions

File tree

‎apps/rush-lib/src/api/ApprovedPackagesPolicy.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ export class ApprovedPackagesPolicy {
5656
}
5757

5858
/**
59-
* A list of NPM package scopes that will be excluded from review (e.g. \"@types\")
59+
* A list of NPM package scopes that will be excluded from review (e.g. `@types`)
6060
*/
6161
public get ignoredNpmScopes(): Set<string> {
6262
return this._ignoredNpmScopes;
@@ -82,7 +82,7 @@ export class ApprovedPackagesPolicy {
8282
* The intent is that the file will be stored in Git and tracked by a branch policy that notifies
8383
* reviewers when a PR attempts to modify the file.
8484
*
85-
* Example filename: "C:\MyRepo\common\config\rush\browser-approved-packages.json"
85+
* Example filename: `C:\MyRepo\common\config\rush\browser-approved-packages.json`
8686
*/
8787
public get browserApprovedPackages(): ApprovedPackagesConfiguration {
8888
return this._browserApprovedPackages;
@@ -98,7 +98,7 @@ export class ApprovedPackagesPolicy {
9898
* The intent is that the file will be stored in Git and tracked by a branch policy that notifies
9999
* reviewers when a PR attempts to modify the file.
100100
*
101-
* Example filename: "C:\MyRepo\common\config\rush\browser-approved-packages.json"
101+
* Example filename: `C:\MyRepo\common\config\rush\browser-approved-packages.json`
102102
*/
103103
public get nonbrowserApprovedPackages(): ApprovedPackagesConfiguration {
104104
return this._nonbrowserApprovedPackages;

‎apps/rush-lib/src/api/CommonVersionsConfiguration.ts‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -118,12 +118,12 @@ export class CommonVersionsConfiguration {
118118
* version, however generally it can be any SemVer range specifier (e.g. "~1.2.3"), and it
119119
* will narrow any (compatible) SemVer range specifier.
120120
*
121-
* For example, suppose local project A depends on an external package B, and B asks
122-
* for C@^1.0.0, which normally would select C@1.5.0. If we specify C@~1.2.3 as our preferred version,
123-
* and it selects C@1.2.9, then that will be installed for B instead of C@1.5.0. Whereas if the
124-
* preferred version was C@~2.0.0 then it would have no effect, because this is incompatible
125-
* with C@^1.0.0. A compatible parent dependency will take precedence over the preferred version;
126-
* for example if A had a direct dependency on C@1.2.2, then B would get C@1.2.2 regardless of the
121+
* For example, suppose local project `A` depends on an external package `B`, and `B` asks
122+
* for `C@^1.0.0`, which normally would select `C@1.5.0`. If we specify `C@~1.2.3` as our preferred version,
123+
* and it selects `C@1.2.9`, then that will be installed for B instead of `C@1.5.0`. Whereas if the
124+
* preferred version was `C@~2.0.0` then it would have no effect, because this is incompatible
125+
* with `C@^1.0.0`. A compatible parent dependency will take precedence over the preferred version;
126+
* for example if `A` had a direct dependency on `C@1.2.2`, then `B` would get `C@1.2.2` regardless of the
127127
* preferred version.
128128
*
129129
* Rush's implementation relies on the package manager's heuristic for avoiding duplicates by

‎apps/rush-lib/src/api/Rush.ts‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,11 +23,11 @@ export class Rush {
2323
private static _version: string;
2424

2525
/**
26-
* This API is used by the @microsoft/rush front end to launch the "rush" command-line.
26+
* This API is used by the `@microsoft/rush` front end to launch the "rush" command-line.
2727
* Third-party tools should not use this API. Instead, they should execute the "rush" binary
2828
* and start a new NodeJS process.
2929
*
30-
* @param launcherVersion - The version of the @microsoft/rush wrapper used to call invoke the CLI.
30+
* @param launcherVersion - The version of the `@microsoft/rush` wrapper used to call invoke the CLI.
3131
* @param isManaged - True if the tool was invoked from within a project with a rush.json file, otherwise false. We
3232
* consider a project without a rush.json to be "unmanaged" and we'll print that to the command line when
3333
* the tool is executed. This is mainly used for debugging purposes.
@@ -46,11 +46,11 @@ export class Rush {
4646
}
4747

4848
/**
49-
* This API is used by the @microsoft/rush front end to launch the "rushx" command-line.
49+
* This API is used by the `@microsoft/rush` front end to launch the "rushx" command-line.
5050
* Third-party tools should not use this API. Instead, they should execute the "rushx" binary
5151
* and start a new NodeJS process.
5252
*
53-
* @param launcherVersion - The version of the @microsoft/rush wrapper used to call invoke the CLI.
53+
* @param launcherVersion - The version of the `@microsoft/rush` wrapper used to call invoke the CLI.
5454
* @param isManaged - True if the tool was invoked from within a project with a rush.json file, otherwise false. We
5555
* consider a project without a rush.json to be "unmanaged" and we'll print that to the command line when
5656
* the tool is executed. This is mainly used for debugging purposes.

‎apps/rush-lib/src/api/RushConfiguration.ts‎

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -418,19 +418,19 @@ export class RushConfiguration {
418418
/**
419419
* The fully resolved path for the "common" folder where Rush will store settings that
420420
* affect all Rush projects. This is always a subfolder of the folder containing "rush.json".
421-
* Example: "C:\MyRepo\common"
421+
* Example: `C:\MyRepo\common`
422422
*/
423423
public get commonFolder(): string {
424424
return this._commonFolder;
425425
}
426426

427427
/**
428428
* The folder where Rush's additional config files are stored. This folder is always a
429-
* subfolder called "config\rush" inside the common folder. (The "common\config" folder
429+
* subfolder called `config\rush` inside the common folder. (The `common\config` folder
430430
* is reserved for configuration files used by other tools.) To avoid confusion or mistakes,
431431
* Rush will report an error if this this folder contains any unrecognized files.
432432
*
433-
* Example: "C:\MyRepo\common\config\rush"
433+
* Example: `C:\MyRepo\common\config\rush`
434434
*/
435435
public get commonRushConfigFolder(): string {
436436
return this._commonRushConfigFolder;
@@ -439,7 +439,7 @@ export class RushConfiguration {
439439
/**
440440
* The folder where temporary files will be stored. This is always a subfolder called "temp"
441441
* under the common folder.
442-
* Example: "C:\MyRepo\common\temp"
442+
* Example: `C:\MyRepo\common\temp`
443443
*/
444444
public get commonTempFolder(): string {
445445
return this._commonTempFolder;
@@ -448,7 +448,7 @@ export class RushConfiguration {
448448
/**
449449
* The folder where automation scripts are stored. This is always a subfolder called "scripts"
450450
* under the common folder.
451-
* Example: "C:\MyRepo\common\scripts"
451+
* Example: `C:\MyRepo\common\scripts`
452452
*/
453453
public get commonScriptsFolder(): string {
454454
return this._commonScriptsFolder;
@@ -460,7 +460,7 @@ export class RushConfiguration {
460460
* reliably handle multiple processes. (For example, if a build box is running
461461
* "rush install" simultaneously for two different working folders, it may fail randomly.)
462462
*
463-
* Example: "C:\MyRepo\common\temp\npm-cache"
463+
* Example: `C:\MyRepo\common\temp\npm-cache`
464464
*/
465465
public get npmCacheFolder(): string {
466466
return this._npmCacheFolder;
@@ -471,7 +471,7 @@ export class RushConfiguration {
471471
* Rush does not rely on the global default folder, because it may be on a different
472472
* hard disk.
473473
*
474-
* Example: "C:\MyRepo\common\temp\npm-tmp"
474+
* Example: `C:\MyRepo\common\temp\npm-tmp`
475475
*/
476476
public get npmTmpFolder(): string {
477477
return this._npmTmpFolder;
@@ -480,7 +480,7 @@ export class RushConfiguration {
480480
/**
481481
* The local folder where PNPM stores a global installation for every installed package
482482
*
483-
* Example: "C:\MyRepo\common\temp\pnpm-store"
483+
* Example: `C:\MyRepo\common\temp\pnpm-store`
484484
*/
485485
public get pnpmStoreFolder(): string {
486486
return this._pnpmStoreFolder;
@@ -489,7 +489,7 @@ export class RushConfiguration {
489489
/**
490490
* The local folder that will store the Yarn package cache.
491491
*
492-
* Example: "C:\MyRepo\common\temp\yarn-cache"
492+
* Example: `C:\MyRepo\common\temp\yarn-cache`
493493
*/
494494
public get yarnCacheFolder(): string {
495495
return this._yarnCacheFolder;
@@ -500,7 +500,7 @@ export class RushConfiguration {
500500
* command uses a temporary copy, whose path is tempShrinkwrapFilename.)
501501
* @remarks
502502
* This property merely reports the filename; the file itself may not actually exist.
503-
* Example: "C:\MyRepo\common\npm-shrinkwrap.json" or "C:\MyRepo\common\shrinkwrap.yaml"
503+
* Example: `C:\MyRepo\common\npm-shrinkwrap.json` or `C:\MyRepo\common\shrinkwrap.yaml`
504504
*/
505505
public get committedShrinkwrapFilename(): string {
506506
return this._committedShrinkwrapFilename;
@@ -511,7 +511,7 @@ export class RushConfiguration {
511511
* This file may get rewritten by the package manager during installation.
512512
* @remarks
513513
* This property merely reports the filename; the file itself may not actually exist.
514-
* Example: "C:\MyRepo\common\temp\npm-shrinkwrap.json" or "C:\MyRepo\common\temp\shrinkwrap.yaml"
514+
* Example: `C:\MyRepo\common\temp\npm-shrinkwrap.json` or `C:\MyRepo\common\temp\shrinkwrap.yaml`
515515
*/
516516
public get tempShrinkwrapFilename(): string {
517517
return this._tempShrinkwrapFilename;
@@ -523,8 +523,8 @@ export class RushConfiguration {
523523
* modified tempShrinkwrapFilename.
524524
* @remarks
525525
* This property merely reports the filename; the file itself may not actually exist.
526-
* Example: "C:\MyRepo\common\temp\npm-shrinkwrap-preinstall.json"
527-
* or "C:\MyRepo\common\temp\shrinkwrap-preinstall.yaml"
526+
* Example: `C:\MyRepo\common\temp\npm-shrinkwrap-preinstall.json`
527+
* or `C:\MyRepo\common\temp\shrinkwrap-preinstall.yaml`
528528
*/
529529
public get tempShrinkwrapPreinstallFilename(): string {
530530
return this._tempShrinkwrapPreinstallFilename;
@@ -547,7 +547,7 @@ export class RushConfiguration {
547547

548548
/**
549549
* The absolute path to Rush's storage in the home directory for the current user. On Windows,
550-
* it would be something like "C:\Users\YourName\.rush".
550+
* it would be something like `C:\Users\YourName\.rush`.
551551
*/
552552
public get rushUserFolder(): string {
553553
return this._rushUserFolder;
@@ -558,7 +558,7 @@ export class RushConfiguration {
558558
* called 'rush-link.json' resides in the Rush common folder.
559559
* Its data structure is defined by IRushLinkJson.
560560
*
561-
* Example: "C:\MyRepo\common\temp\rush-link.json"
561+
* Example: `C:\MyRepo\common\temp\rush-link.json`
562562
*/
563563
public get rushLinkJsonFilename(): string {
564564
return this._rushLinkJsonFilename;
@@ -574,7 +574,7 @@ export class RushConfiguration {
574574
/**
575575
* The absolute path to the locally installed NPM tool. If "rush install" has not
576576
* been run, then this file may not exist yet.
577-
* Example: "C:\MyRepo\common\temp\npm-local\node_modules\.bin\npm"
577+
* Example: `C:\MyRepo\common\temp\npm-local\node_modules\.bin\npm`
578578
*/
579579
public get packageManagerToolFilename(): string {
580580
return this._packageManagerToolFilename;
@@ -611,7 +611,7 @@ export class RushConfiguration {
611611
* [Part of the "gitPolicy" feature.]
612612
* A list of regular expressions describing allowable email patterns for Git commits.
613613
* They are case-insensitive anchored JavaScript RegExps.
614-
* Example: ".*@example\.com"
614+
* Example: `".*@example\.com"`
615615
* This array will never be undefined.
616616
*/
617617
public get gitAllowedEmailRegExps(): string[] {
@@ -621,7 +621,7 @@ export class RushConfiguration {
621621
/**
622622
* [Part of the "gitPolicy" feature.]
623623
* An example valid email address that conforms to one of the allowedEmailRegExps.
624-
* Example: "foxtrot@example\.com"
624+
* Example: `"foxtrot@example\.com"`
625625
* This will never be undefined, and will always be nonempty if gitAllowedEmailRegExps is used.
626626
*/
627627
public get gitSampleEmail(): string {
@@ -704,7 +704,7 @@ export class RushConfiguration {
704704
/**
705705
* This is used e.g. by command-line interfaces such as "rush build --to example".
706706
* If "example" is not a project name, then it also looks for a scoped name
707-
* like "@something/example". If exactly one project matches this heuristic, it
707+
* like `@something/example`. If exactly one project matches this heuristic, it
708708
* is returned. Otherwise, undefined is returned.
709709
*/
710710
public findProjectByShorthandName(shorthandProjectName: string): RushConfigurationProject | undefined {

‎apps/rush-lib/src/api/RushConfigurationProject.ts‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ export class RushConfigurationProject {
124124
* The name of the NPM package. An error is reported if this name is not
125125
* identical to packageJson.name.
126126
*
127-
* Example: "@scope/MyProject"
127+
* Example: `@scope/MyProject`
128128
*/
129129
public get packageName(): string {
130130
return this._packageName;
@@ -133,7 +133,7 @@ export class RushConfigurationProject {
133133
/**
134134
* The full path of the folder that contains the project to be built by Rush.
135135
*
136-
* Example: "C:\MyRepo\libraries\my-project"
136+
* Example: `C:\MyRepo\libraries\my-project`
137137
*/
138138
public get projectFolder(): string {
139139
return this._projectFolder;
@@ -142,7 +142,7 @@ export class RushConfigurationProject {
142142
/**
143143
* The relative path of the folder that contains the project to be built by Rush.
144144
*
145-
* Example: "libraries\my-project"
145+
* Example: `libraries\my-project`
146146
*/
147147
public get projectRelativeFolder(): string {
148148
return this._projectRelativeFolder;
@@ -192,10 +192,10 @@ export class RushConfigurationProject {
192192

193193
/**
194194
* The unique name for the temporary project that will be generated in the Common folder.
195-
* For example, if the project name is "@scope/MyProject", the temporary project name
196-
* might be "@rush-temp/MyProject-2".
195+
* For example, if the project name is `@scope/MyProject`, the temporary project name
196+
* might be `@rush-temp/MyProject-2`.
197197
*
198-
* Example: "@rush-temp/MyProject-2"
198+
* Example: `@rush-temp/MyProject-2`
199199
*/
200200
public get tempProjectName(): string {
201201
return this._tempProjectName;
@@ -204,7 +204,7 @@ export class RushConfigurationProject {
204204
/**
205205
* The unscoped temporary project name
206206
*
207-
* Example: "my-project-2"
207+
* Example: `my-project-2`
208208
*/
209209
public get unscopedTempProjectName(): string {
210210
return this._unscopedTempProjectName;

‎apps/rush-lib/src/logic/RushConstants.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,13 +46,13 @@ export namespace RushConstants {
4646

4747
/**
4848
* The folder name ("temp") under the common folder where temporary files will be stored.
49-
* Example: "C:\MyRepo\common\temp"
49+
* Example: `C:\MyRepo\common\temp`
5050
*/
5151
export const rushTempFolderName: string = 'temp';
5252

5353
/**
5454
* The folder name ("projects") where temporary projects will be stored.
55-
* Example: "C:\MyRepo\common\temp\projects"
55+
* Example: `C:\MyRepo\common\temp\projects`
5656
*/
5757
export const rushTempProjectsFolderName: string = 'projects';
5858

‎apps/rush-lib/src/logic/base/BasePackage.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -108,9 +108,9 @@ export class BasePackage {
108108
* Used by "npm link" to simulate a temp project that is missing from the common/node_modules
109109
* folder (e.g. because it was added after the shrinkwrap file was regenerated).
110110
* @param packageJsonFilename - Filename of the source package.json
111-
* Example: c:\MyRepo\common\temp\projects\project1\package.json
111+
* Example: `C:\MyRepo\common\temp\projects\project1\package.json`
112112
* @param targetFolderName - Filename where it should have been installed
113-
* Example: c:\MyRepo\common\temp\node_modules\@rush-temp\project1
113+
* Example: `C:\MyRepo\common\temp\node_modules\@rush-temp\project1`
114114
*/
115115
public static createVirtualTempPackage(packageJsonFilename: string, installFolderName: string): BasePackage {
116116
const packageJson: IRushTempPackageJson = JsonFile.load(packageJsonFilename);

‎apps/rush-lib/src/logic/npm/NpmPackage.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -73,9 +73,9 @@ export class NpmPackage extends BasePackage {
7373
* Used by "npm link" to simulate a temp project that is missing from the common/node_modules
7474
* folder (e.g. because it was added after the shrinkwrap file was regenerated).
7575
* @param packageJsonFilename - Filename of the source package.json
76-
* Example: c:\MyRepo\common\temp\projects\project1\package.json
76+
* Example: `C:\MyRepo\common\temp\projects\project1\package.json`
7777
* @param targetFolderName - Filename where it should have been installed
78-
* Example: c:\MyRepo\common\temp\node_modules\@rush-temp\project1
78+
* Example: `C:\MyRepo\common\temp\node_modules\@rush-temp\project1`
7979
*/
8080
public static createVirtualTempPackage(packageJsonFilename: string, installFolderName: string): NpmPackage {
8181
const packageJson: IPackageJson = JsonFile.load(packageJsonFilename);

‎apps/rush-lib/src/utilities/AsyncRecycler.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ export class AsyncRecycler {
3333

3434
/**
3535
* The full path of the recycler folder.
36-
* Example: "C:\MyRepo\common\rush-recycler"
36+
* Example: `C:\MyRepo\common\rush-recycler`
3737
*/
3838
public get recyclerFolder(): string {
3939
return this._recyclerFolder;

‎core-build/gulp-core-build/src/tasks/GulpTask.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -228,7 +228,7 @@ export abstract class GulpTask<TTaskConfig> implements IExecutable {
228228
* This function is called once to execute the task. It calls executeTask() and handles the return
229229
* value from that function. It also provides some utilities such as logging how long each
230230
* task takes to execute.
231-
* @param config - the buildConfig which is applied to the task instance before execution\
231+
* @param config - the buildConfig which is applied to the task instance before execution
232232
* @returns a Promise which is completed when the task is finished executing
233233
*/
234234
public execute(config: IBuildConfig): Promise<void> {

0 commit comments

Comments
 (0)