Merge branch 'master' into synonyms

# Conflicts:
#	tsdoc/src/__tests__/ParsingBasics.test.ts
#	tsdoc/src/__tests__/__snapshots__/ParsingBasics.test.ts.snap
#	tsdoc/src/parser/NodeParser.ts

Author: rbuckton

.gitattributes

@@ -73,6 +73,6 @@ yarn.lock                    merge=binary
 # syntax highlighters such as GitHub's from highlighting these comments as errors.  Your text editor
 # may also require a special configuration to allow comments in JSON.
 #
-# For more information, see this issue: https://github.com/Microsoft/web-build-tools/issues/1088
+# For more information, see this issue: https://github.com/microsoft/rushstack/issues/1088
 #
 *.json                       linguist-language=JSON-with-Comments

.gitignore

@@ -55,14 +55,14 @@ jspm_packages/
 # next.js build output
 .next
 
-# Common toolchain intermediate files
-temp
+# OS X temporary files
+.DS_Store
 
-# Rush files
-common/temp/**
-package-deps.json
-.rush/temp/**
+# Rush temporary files
+common/temp/
+**/.rush/temp/
 
+# Common toolchain intermediate files
+temp
 lib
 dist
-temp

README.md

@@ -55,7 +55,7 @@ The TSDoc specification aims to meet these requirements:
 - **Common core**: Common  tags such as `@param` and `@returns` will have consistent behavior across all tools.
 - **Extensible**: Each tool can supplement the core tags with custom tags for specialized scenarios.
 - **Interoperable**: The TSDoc standard guarantees that unsupported custom tags won't interfere with parsing of other content. TSDoc also eliminates Markdown ambiguities.  (Are backticks allowed inside a `{@link}` tag?  What happens if there is only one backtick? etc.)
-- **Multi-package support**:  Many teams ship a collection of NPM packages that work together and are documented as a set.  The cross-referencing syntax (e.g. `{@link}` or `{@inheritdoc}`) needs a portable way to reference API items imported from other packages.  We also define  *package.json* metadata that enables tooling to detect whether a dependency's *.d.ts doc comments should be parsed as TSDoc or not.
+- **Multi-package support**:  Many teams ship a collection of NPM packages that work together and are documented as a set.  The cross-referencing syntax (e.g. `{@link}` or `{@inheritDoc}`) needs a portable way to reference API items imported from other packages.  We also define  *package.json* metadata that enables tooling to detect whether a dependency's *.d.ts doc comments should be parsed as TSDoc or not.
 - **Open standard**: TSDoc is an open source, community-driven standard.  You are encouraged to contribute your own ideas and pull requests.
 
 The **@microsoft/tsdoc** library package brings in some additional goals:

api-demo/package.json

@@ -5,7 +5,7 @@
   "description": "A code sample that illustrates usage of the API for @microsoft/tsdoc",
   "license": "MIT",
   "dependencies": {
-    "@microsoft/tsdoc": "0.12.16",
+    "@microsoft/tsdoc": "0.12.19",
     "@types/node": "10.17.5",
     "colors": "~1.3.3"
   },

common/changes/@microsoft/tsdoc/patch-3_2020-04-30-01-14.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/tsdoc",
+      "comment": "Improve documentation for `@inheritDoc`",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/tsdoc",
+  "email": "arnog@users.noreply.github.com"
+}

common/config/rush/command-line.json

@@ -164,13 +164,40 @@
     //    * (Required) A list of custom commands and/or built-in Rush commands that this parameter may
     //    * be used with.  The parameter will be appended to the shell command that Rush invokes.
     //    */
-    //    "associatedCommands": [ "build", "rebuild" ]
+    //   "associatedCommands": [ "build", "rebuild" ]
     // },
     // 
     // {
     //   /**
     //    * (Required) Determines the type of custom parameter.
-    //    * A "flag" is a custom command-line parameter whose presence acts as an on/off switch.
+    //    * A "string" is a custom command-line parameter whose value is a simple text string.
+    //    */
+    //   "parameterKind": "string",
+    //   "longName": "--my-string",
+    //   "description": "A custom string parameter for the \"my-global-command\" custom command",
+    // 
+    //   "associatedCommands": [ "my-global-command" ],
+    // 
+    //   /**
+    //    * The name of the argument, which will be shown in the command-line help.
+    //    *
+    //    * For example, if the parameter name is '--count" and the argument name is "NUMBER",
+    //    * then the command-line help would display "--count NUMBER".  The argument name must
+    //    * be comprised of upper-case letters, numbers, and underscores.  It should be kept short.
+    //    */
+    //   "argumentName": "SOME_TEXT",
+    // 
+    //   /**
+    //    * If true, this parameter must be included with the command.  The default is false.
+    //    */
+    //   "required": false
+    // },
+    // 
+    // {
+    //   /**
+    //    * (Required) Determines the type of custom parameter.
+    //    * A "choice" is a custom command-line parameter whose argument must be chosen from a list of
+    //    * allowable alternatives.
     //    */
     //   "parameterKind": "choice",
     //   "longName": "--my-choice",
@@ -179,6 +206,11 @@
     //   "associatedCommands": [ "my-global-command" ],
     // 
     //   /**
+    //    * If true, this parameter must be included with the command.  The default is false.
+    //    */
+    //    "required": false,
+    // 
+    //   /**
     //    * Normally if a parameter is omitted from the command line, it will not be passed
     //    * to the shell command. this value will be inserted by default.  Whereas if a "defaultValue"
     //    * is defined, the parameter will always be passed to the shell command, and will use the

common/config/rush/common-versions.json

@@ -6,10 +6,14 @@
   "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/common-versions.schema.json",
 
   /**
-   * A table that specifies a "preferred version" for a dependency package. The "preferred version"
-   * is typically used to hold an indirect dependency back to a specific version, however generally
-   * it can be any SemVer range specifier (e.g. "~1.2.3"), and it will narrow any (compatible)
-   * SemVer range specifier.  See the Rush documentation for details about this feature.
+   * A table that specifies a "preferred version" for a given NPM package.  This feature is typically used
+   * to hold back an indirect dependency to a specific older version, or to reduce duplication of indirect dependencies.
+   *
+   * The "preferredVersions" value can be any SemVer range specifier (e.g. "~1.2.3").  Rush injects these values into
+   * the "dependencies" field of the top-level common/temp/package.json, which influences how the package manager
+   * will calculate versions.  The specific effect depends on your package manager.  Generally it will have no
+   * effect on an incompatible or already constrained SemVer range.  If you are using PNPM, similar effects can be
+   * achieved using the pnpmfile.js hook.  See the Rush documentation for more details.
    *
    * After modifying this field, it's recommended to run "rush update --full" so that the package manager
    * will recalculate all version selections.
@@ -24,6 +28,20 @@
     "@types/jest-diff": "20.0.1"
   },
 
+  /**
+   * When set to true, for all projects in the repo, all dependencies will be automatically added as preferredVersions,
+   * except in cases where different projects specify different version ranges for a given dependency.  For older
+   * package managers, this tended to reduce duplication of indirect dependencies.  However, it can sometimes cause
+   * trouble for indirect dependencies with incompatible peerDependencies ranges.
+   *
+   * The default value is true.  If you're encountering installation errors related to peer dependencies,
+   * it's recommended to set this to false.
+   *
+   * After modifying this field, it's recommended to run "rush update --full" so that the package manager
+   * will recalculate all version selections.
+   */
+  // "implicitlyPreferredVersions": false,
+
   /**
    * The "rush check" command can be used to enforce that every project in the repo must specify
    * the same SemVer range for a given dependency.  However, sometimes exceptions are needed.