Merge pull request #547 from AArnott/libtemplateUpdate

AArnott · web-flow · commit dafeb5846702 · 2022-10-01T13:31:16.000-06:00
Merge latest Library.Template
diff --git a/.editorconfig b/.editorconfig
@@ -170,5 +170,14 @@ dotnet_diagnostic.SA1600.severity = suggestion
 # IDE1006: Naming Styles - StyleCop handles these for us
 dotnet_diagnostic.IDE1006.severity = none
 
+dotnet_diagnostic.DOC100.severity = silent
+dotnet_diagnostic.DOC104.severity = warning
+dotnet_diagnostic.DOC105.severity = warning
+dotnet_diagnostic.DOC106.severity = warning
+dotnet_diagnostic.DOC107.severity = warning
+dotnet_diagnostic.DOC108.severity = warning
+dotnet_diagnostic.DOC200.severity = warning
+dotnet_diagnostic.DOC202.severity = warning
+
 [*.sln]
 indent_style = tab
diff --git a/Directory.Build.props b/Directory.Build.props
@@ -18,6 +18,9 @@
     <!-- https://github.com/dotnet/msbuild/blob/main/documentation/ProjectReference-Protocol.md#setplatform-negotiation -->
     <EnableDynamicPlatformResolution>true</EnableDynamicPlatformResolution>
 
+    <!-- Opt in till https://github.com/NuGet/Home/issues/9803 makes this the default. -->
+    <RestoreUseStaticGraphEvaluation>true</RestoreUseStaticGraphEvaluation>
+
     <!-- This entire repo has just one version.json file, so compute the version once and share with all projects in a large build. -->
     <GitVersionBaseDirectory>$(MSBuildThisFileDirectory)</GitVersionBaseDirectory>
 
@@ -44,10 +47,12 @@
 
   <ItemGroup>
     <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.1.1" PrivateAssets="all" />
-    <PackageReference Include="Nerdbank.GitVersioning" Version="3.5.109" PrivateAssets="all" />
+    <PackageReference Include="Nerdbank.GitVersioning" Version="3.5.113" PrivateAssets="all" />
     <PackageReference Include="Nullable" Version="1.3.1" PrivateAssets="all" />
     <!-- Use the Unstable package ID so that update tools will help us keep it current even though it seems to be ever-unstable lately. -->
     <PackageReference Include="StyleCop.Analyzers.Unstable" Version="1.2.0.435" PrivateAssets="all" />
+    <PackageReference Include="CSharpIsNullAnalyzer" Version="0.1.329" PrivateAssets="all" />
+    <PackageReference Include="DotNetAnalyzers.DocumentationAnalyzers" Version="1.0.0-beta.59" PrivateAssets="all" />
   </ItemGroup>
 
   <ItemGroup>
diff --git a/ext/.editorconfig b/ext/.editorconfig
@@ -2,3 +2,6 @@
 
 [*.{cs,csx,vb,vbx,h,cpp,idl}]
 dotnet_analyzer_diagnostic.severity = none
+
+[*.cs]
+dotnet_diagnostic.DOC104.severity = silent
diff --git a/src/Nerdbank.Streams/BufferTextWriter.cs b/src/Nerdbank.Streams/BufferTextWriter.cs
@@ -256,7 +256,7 @@ private void EncodeCharactersIfBufferFull()
         /// <summary>
         /// Encodes characters written so far to a buffer provided by the underyling <see cref="bufferWriter"/>.
         /// </summary>
-        /// <param name="flushEncoder"><c>true</c> to flush the characters in the encoder; useful when finalizing the output.</param>
+        /// <param name="flushEncoder"><see langword="true"/> to flush the characters in the encoder; useful when finalizing the output.</param>
         private void EncodeCharacters(bool flushEncoder)
         {
             if (this.charBufferPosition > 0)
diff --git a/src/Nerdbank.Streams/MultiplexingStream.Channel.cs b/src/Nerdbank.Streams/MultiplexingStream.Channel.cs
@@ -579,7 +579,7 @@ internal bool TryAcceptOffer(ChannelOptions channelOptions)
             /// Occurs when the remote party has accepted our offer of this channel.
             /// </summary>
             /// <param name="acceptanceParameters">The channel parameters provided by the accepting party.</param>
-            /// <returns>A value indicating whether the acceptance went through; <c>false</c> if the channel is already accepted, rejected or offer rescinded.</returns>
+            /// <returns>A value indicating whether the acceptance went through; <see langword="false"/> if the channel is already accepted, rejected or offer rescinded.</returns>
             internal bool OnAccepted(AcceptanceParameters acceptanceParameters)
             {
                 lock (this.SyncObject)
diff --git a/src/Nerdbank.Streams/MultiplexingStream.ChannelOptions.cs b/src/Nerdbank.Streams/MultiplexingStream.ChannelOptions.cs
@@ -38,7 +38,7 @@ public ChannelOptions()
             /// <summary>
             /// Gets or sets an existing <see cref="IDuplexPipe"/> instance used to exchange data with the channel.
             /// </summary>
-            /// <value>The default is <c>null</c>.</value>
+            /// <value>The default is <see langword="null"/>.</value>
             /// <remarks>
             /// <para>
             /// This property supports high throughput scenarios where channel data ultimately goes to a <see cref="PipeWriter"/> and <see cref="PipeReader"/> that already exist.
@@ -51,7 +51,7 @@ public ChannelOptions()
             /// the value of <see cref="ChannelReceivingWindowSize"/> and <see cref="Options.DefaultChannelReceivingWindowSize"/>.
             /// </para>
             /// </remarks>
-            /// <exception cref="ArgumentException">Thrown if set to an <see cref="IDuplexPipe"/> that returns <c>null</c> for either of its properties.</exception>
+            /// <exception cref="ArgumentException">Thrown if set to an <see cref="IDuplexPipe"/> that returns <see langword="null"/> for either of its properties.</exception>
             public IDuplexPipe? ExistingPipe
             {
                 get => this.existingPipe;
diff --git a/src/Nerdbank.Streams/MultiplexingStream.Options.cs b/src/Nerdbank.Streams/MultiplexingStream.Options.cs
@@ -91,7 +91,7 @@ public Options(Options copyFrom)
             /// and copies the values from another instance into this one.
             /// </summary>
             /// <param name="copyFrom">The instance to copy values from.</param>
-            /// <param name="frozen"><c>true</c> to freeze this copy.</param>
+            /// <param name="frozen"><see langword="true"/> to freeze this copy.</param>
             private Options(Options copyFrom, bool frozen)
                 : this(copyFrom)
             {
@@ -160,10 +160,10 @@ public int ProtocolMajorVersion
 
             /// <summary>
             /// Gets or sets a factory for <see cref="TraceSource"/> instances to attach to a newly opened <see cref="Channel"/>
-            /// when its <see cref="ChannelOptions.TraceSource"/> is <c>null</c>.
+            /// when its <see cref="ChannelOptions.TraceSource"/> is <see langword="null"/>.
             /// </summary>
             /// <remarks>
-            /// <para>The delegate receives a channel ID and name, and may return a <see cref="TraceSource"/> or <c>null</c>.</para>
+            /// <para>The delegate receives a channel ID and name, and may return a <see cref="TraceSource"/> or <see langword="null"/>.</para>
             /// <para>This delegate will not be invoked if <see cref="DefaultChannelTraceSourceFactoryWithQualifier"/> has been set to a non-null value.</para>
             /// </remarks>
             [Obsolete("Use " + nameof(DefaultChannelTraceSourceFactoryWithQualifier) + " instead.")]
@@ -179,10 +179,10 @@ public int ProtocolMajorVersion
 
             /// <summary>
             /// Gets or sets a factory for <see cref="TraceSource"/> instances to attach to a newly opened <see cref="Channel"/>
-            /// when its <see cref="ChannelOptions.TraceSource"/> is <c>null</c>.
+            /// when its <see cref="ChannelOptions.TraceSource"/> is <see langword="null"/>.
             /// </summary>
             /// <remarks>
-            /// <para>The delegate receives a channel ID and name, and may return a <see cref="TraceSource"/> or <c>null</c>.</para>
+            /// <para>The delegate receives a channel ID and name, and may return a <see cref="TraceSource"/> or <see langword="null"/>.</para>
             /// <para>This delegate supersedes the obsolete <see cref="DefaultChannelTraceSourceFactory"/> as this one provides detail about whether the channel was offered locally or remotely.</para>
             /// </remarks>
             public Func<QualifiedChannelId, string, TraceSource?>? DefaultChannelTraceSourceFactoryWithQualifier
diff --git a/src/Nerdbank.Streams/MultiplexingStream.cs b/src/Nerdbank.Streams/MultiplexingStream.cs
@@ -240,7 +240,7 @@ private enum TraceEventId
 
         /// <summary>
         /// Gets a factory for <see cref="TraceSource"/> instances to attach to a newly opened <see cref="Channel"/>
-        /// when its <see cref="ChannelOptions.TraceSource"/> is <c>null</c>.
+        /// when its <see cref="ChannelOptions.TraceSource"/> is <see langword="null"/>.
         /// </summary>
         private Func<QualifiedChannelId, string, TraceSource?>? DefaultChannelTraceSourceFactory { get; }
 
@@ -715,9 +715,9 @@ public async ValueTask DisposeAsync()
         /// </summary>
         /// <param name="stream">The stream to read from.</param>
         /// <param name="buffer">The buffer to fill.</param>
-        /// <param name="throwOnEmpty"><c>true</c> to throw if 0 bytes are read before the stream before the end of stream is encountered; <c>false</c> to simply return <c>false</c> when that happens.</param>
+        /// <param name="throwOnEmpty"><see langword="true"/> to throw if 0 bytes are read before the stream before the end of stream is encountered; <see langword="false"/> to simply return <see langword="false"/> when that happens.</param>
         /// <param name="cancellationToken">A cancellation token.</param>
-        /// <returns><c>true</c> if the buffer was filled as required; <c>false</c> if the stream was empty and no bytes were read, if <paramref name="throwOnEmpty"/> is <c>false</c>.</returns>
+        /// <returns><see langword="true"/> if the buffer was filled as required; <see langword="false"/> if the stream was empty and no bytes were read, if <paramref name="throwOnEmpty"/> is <see langword="false"/>.</returns>
         /// <exception cref="EndOfStreamException">Thrown if the end of the stream was reached before the buffer was filled (unless <paramref name="throwOnEmpty"/> is false and 0 bytes were read).</exception>
         private static async ValueTask<bool> ReadToFillAsync(Stream stream, Memory<byte> buffer, bool throwOnEmpty, CancellationToken cancellationToken)
         {
diff --git a/src/Nerdbank.Streams/Nerdbank.Streams.csproj b/src/Nerdbank.Streams/Nerdbank.Streams.csproj
@@ -13,7 +13,7 @@
     <PackageReference Include="Microsoft.CodeAnalysis.PublicApiAnalyzers" Version="3.3.3" PrivateAssets="all" />
     <PackageReference Include="Microsoft.VisualStudio.Threading" Version="$(VSThreadingVersion)" PrivateAssets="build;analyzers;compile" />
     <PackageReference Include="Microsoft.VisualStudio.Threading.Analyzers" Version="$(VSThreadingVersion)" PrivateAssets="all" />
-    <PackageReference Include="Microsoft.VisualStudio.Validation" Version="17.0.53" />
+    <PackageReference Include="Microsoft.VisualStudio.Validation" Version="17.0.64" />
     <PackageReference Include="System.IO.Pipelines" Version="6.0.3" />
     <PackageReference Include="System.Runtime.CompilerServices.Unsafe" Version="6.0.0" />
   </ItemGroup>
diff --git a/src/Nerdbank.Streams/PipeExtensions.cs b/src/Nerdbank.Streams/PipeExtensions.cs
@@ -35,7 +35,7 @@ public static partial class PipeExtensions
         /// Exposes a full-duplex pipe as a <see cref="Stream"/>.
         /// </summary>
         /// <param name="pipe">The pipe to wrap as a stream.</param>
-        /// <param name="ownsPipe"><c>true</c> to complete the underlying reader and writer when the <see cref="Stream"/> is disposed; <c>false</c> to keep them open.</param>
+        /// <param name="ownsPipe"><see langword="true"/> to complete the underlying reader and writer when the <see cref="Stream"/> is disposed; <see langword="false"/> to keep them open.</param>
         /// <returns>The wrapping stream.</returns>
         public static Stream AsStream(this IDuplexPipe pipe, bool ownsPipe) => FullDuplexStream.Splice(pipe.Input.AsStream(leaveOpen: !ownsPipe), pipe.Output.AsStream(leaveOpen: !ownsPipe));
 
diff --git a/src/Nerdbank.Streams/Sequence`1.cs b/src/Nerdbank.Streams/Sequence`1.cs
@@ -88,7 +88,7 @@ public Sequence(ArrayPool<T> arrayPool)
         /// in which case the higher of the two minimums dictate the minimum array size that will be allocated.
         /// </para>
         /// <para>
-        /// If <see cref="AutoIncreaseMinimumSpanLength"/> is <c>true</c>, this value may be automatically increased as the length of a sequence grows.
+        /// If <see cref="AutoIncreaseMinimumSpanLength"/> is <see langword="true"/>, this value may be automatically increased as the length of a sequence grows.
         /// </para>
         /// </remarks>
         public int MinimumSpanLength { get; set; } = 0;
@@ -386,7 +386,7 @@ private class SequenceSegment : ReadOnlySequenceSegment<T>
 
             /// <summary>
             /// Gets the tracker for the underlying array for this segment, which can be used to recycle the array when we're disposed of.
-            /// Will be <c>null</c> if using an array pool, in which case the memory is held by <see cref="array"/>.
+            /// Will be <see langword="null"/> if using an array pool, in which case the memory is held by <see cref="array"/>.
             /// </summary>
             internal IMemoryOwner<T>? MemoryOwner { get; private set; }
 
diff --git a/src/Nerdbank.Streams/StreamPipeReader.cs b/src/Nerdbank.Streams/StreamPipeReader.cs
@@ -64,7 +64,7 @@ public StreamPipeReader(Stream stream)
         /// </summary>
         /// <param name="stream">The stream to read from.</param>
         /// <param name="bufferSize">A hint at the size of messages that are commonly transferred. Use 0 for a commonly reasonable default.</param>
-        /// <param name="leaveOpen"><c>true</c> to leave the underlying <paramref name="stream"/> open after calling <see cref="PipeReader.Complete(Exception)"/>; <c>false</c> to close the stream.</param>
+        /// <param name="leaveOpen"><see langword="true"/> to leave the underlying <paramref name="stream"/> open after calling <see cref="PipeReader.Complete(Exception)"/>; <see langword="false"/> to close the stream.</param>
         public StreamPipeReader(Stream stream, int bufferSize, bool leaveOpen)
         {
             Requires.NotNull(stream, nameof(stream));
diff --git a/src/Nerdbank.Streams/Utilities.cs b/src/Nerdbank.Streams/Utilities.cs
@@ -47,7 +47,7 @@ internal static void ValidateBufferIndexAndCount<T>(T[] buffer, int index, int c
         /// <typeparam name="T">The element to remove.</typeparam>
         /// <param name="queue">The queue to modify.</param>
         /// <param name="valueToRemove">The value to remove.</param>
-        /// <returns><c>true</c> if the value was found and removed; <c>false</c> if no match was found.</returns>
+        /// <returns><see langword="true"/> if the value was found and removed; <see langword="false"/> if no match was found.</returns>
         /// <remarks>
         /// If a value appears multiple times in the queue, only its first entry is removed.
         /// </remarks>
diff --git a/src/nerdbank-streams/yarn.lock b/src/nerdbank-streams/yarn.lock
@@ -1411,18 +1411,18 @@ isobject@^3.0.0, isobject@^3.0.1:
   resolved "https://registry.yarnpkg.com/isobject/-/isobject-3.0.1.tgz#4e431e92b11a9731636aa1f9c8d1ccbcfdab78df"
   integrity sha512-WhB9zCku7EGTj/HQQRz5aUQEUeoQZH2bWcltRErOpymJ4boYE6wL9Tbr23krRPSZ+C5zqNSrSw+Cc7sZZ4b7vg==
 
-jasmine-core@^4.3.0:
-  version "4.3.0"
-  resolved "https://registry.yarnpkg.com/jasmine-core/-/jasmine-core-4.3.0.tgz#aee841fbe7373c2586ed8d8d48f5cc4a88be8390"
-  integrity sha512-qybtBUesniQdW6n+QIHMng2vDOHscIC/dEXjW+JzO9+LoAZMb03RCUC5xFOv/btSKPm1xL42fn+RjlU4oB42Lg==
+jasmine-core@^4.4.0:
+  version "4.4.0"
+  resolved "https://registry.yarnpkg.com/jasmine-core/-/jasmine-core-4.4.0.tgz#848fe45c1839cacaf1f2429d400d1d4f85d2856a"
+  integrity sha512-+l482uImx5BVd6brJYlaHe2UwfKoZBqQfNp20ZmdNfsjGFTemGfqHLsXjKEW23w9R/m8WYeFc9JmIgjj6dUtAA==
 
 jasmine@^4.0.2:
-  version "4.3.0"
-  resolved "https://registry.yarnpkg.com/jasmine/-/jasmine-4.3.0.tgz#f99e9bc2a94e8281d2490482d53a3406760bd7f4"
-  integrity sha512-ieBmwkd8L1DXnvSnxx7tecXgA0JDgMXPAwBcqM4lLPedJeI9hTHuWifPynTC+dLe4Y+GkSPSlbqqrmYIgGzYUw==
+  version "4.4.0"
+  resolved "https://registry.yarnpkg.com/jasmine/-/jasmine-4.4.0.tgz#e3e359723d9679993b70de3e0441517c154b9647"
+  integrity sha512-xrbOyYkkCvgduNw7CKktDtNb+BwwBv/zvQeHpTkbxqQ37AJL5V4sY3jHoMIJPP/hTc3QxLVwOyxc87AqA+kw5g==
   dependencies:
     glob "^7.1.6"
-    jasmine-core "^4.3.0"
+    jasmine-core "^4.4.0"
 
 js-tokens@^4.0.0:
   version "4.0.0"
@@ -1680,9 +1680,9 @@ nanomatch@^1.2.9:
     to-regex "^3.0.1"
 
 nerdbank-gitversioning@^3.4.231:
-  version "3.5.109"
-  resolved "https://registry.yarnpkg.com/nerdbank-gitversioning/-/nerdbank-gitversioning-3.5.109.tgz#9a35fc516aaceee2773e966d446309521e2a4325"
-  integrity sha512-CQFu4vhjQ4o4cicJaklsp4RNTCyxBW2rKig/Aej/xNgkmjo8a87NWLj55WmMhV79soC88eRVRRct/SEPArnW3A==
+  version "3.5.113"
+  resolved "https://registry.yarnpkg.com/nerdbank-gitversioning/-/nerdbank-gitversioning-3.5.113.tgz#55e697533369d6029b0d17ae2a4e9c87c778257f"
+  integrity sha512-IxavqvSV/6CQSr4CaqWA72qqhuTWUEp1C12CQM3RAW9YBjNJb0/zXaG1LfY6HoC6uS9NIDuuwQ5ptXMHnq7BfQ==
   dependencies:
     camel-case "^4.1.2"
 
@@ -2496,9 +2496,9 @@ typedarray@^0.0.6:
   integrity sha512-/aCDEGatGvZ2BIk+HmLf4ifCJFwvKFNb9/JeZPMulfgFracn9QFcAf5GO8B/mweUjSoblS5In0cWhqpfs/5PQA==
 
 typescript@^4.3.5:
-  version "4.8.2"
-  resolved "https://registry.yarnpkg.com/typescript/-/typescript-4.8.2.tgz#e3b33d5ccfb5914e4eeab6699cf208adee3fd790"
-  integrity sha512-C0I1UsrrDHo2fYI5oaCGbSejwX4ch+9Y5jTQELvovfmFkK3HHSZJB8MSJcWLmCUBzQBchCrZ9rMRV6GuNrvGtw==
+  version "4.8.4"
+  resolved "https://registry.yarnpkg.com/typescript/-/typescript-4.8.4.tgz#c464abca159669597be5f96b8943500b238e60e6"
+  integrity sha512-QCh+85mCy+h0IGff8r5XWzOVSbBO+KfeYrMQh7NJ58QujwcE22u+NUSmUxqF+un70P9GXKxa2HCNiTTMJknyjQ==
 
 unc-path-regex@^0.1.2:
   version "0.1.2"
diff --git a/test/Nerdbank.Streams.Tests/Nerdbank.Streams.Tests.csproj b/test/Nerdbank.Streams.Tests/Nerdbank.Streams.Tests.csproj
@@ -24,7 +24,7 @@
     <PackageReference Include="xunit.skippablefact" Version="1.4.13" />
     <PackageReference Include="xunit.runner.console" Version="2.4.2" />
     <PackageReference Include="xunit.runner.visualstudio" Version="2.4.5" />
-    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.3.1" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.3.2" />
     <PackageReference Include="Moq" Version="4.18.2" />
     <PackageReference Include="System.IO.Pipes" Version="4.3.0" />
     <PackageReference Include="Microsoft.AspNetCore.TestHost" Version="2.2.0" />
diff --git a/test/Nerdbank.Streams.Tests/TestBase.cs b/test/Nerdbank.Streams.Tests/TestBase.cs

Original file line number	Diff line number	Diff line change
`@@ -256,7 +256,7 @@ private void EncodeCharactersIfBufferFull()`
`256`	`256`	`/// <summary>`
`257`	`257`	`/// Encodes characters written so far to a buffer provided by the underyling <see cref="bufferWriter"/>.`
`258`	`258`	`/// </summary>`
`259`		`- /// <param name="flushEncoder"><c>true</c> to flush the characters in the encoder; useful when finalizing the output.</param>`
	`259`	`+ /// <param name="flushEncoder"><see langword="true"/> to flush the characters in the encoder; useful when finalizing the output.</param>`
`260`	`260`	`private void EncodeCharacters(bool flushEncoder)`
`261`	`261`	`{`
`262`	`262`	`if (this.charBufferPosition > 0)`
Original file line number	Diff line number	Diff line change
`@@ -579,7 +579,7 @@ internal bool TryAcceptOffer(ChannelOptions channelOptions)`
`579`	`579`	`/// Occurs when the remote party has accepted our offer of this channel.`
`580`	`580`	`/// </summary>`
`581`	`581`	`/// <param name="acceptanceParameters">The channel parameters provided by the accepting party.</param>`
`582`		`- /// <returns>A value indicating whether the acceptance went through; <c>false</c> if the channel is already accepted, rejected or offer rescinded.</returns>`
	`582`	`+ /// <returns>A value indicating whether the acceptance went through; <see langword="false"/> if the channel is already accepted, rejected or offer rescinded.</returns>`
`583`	`583`	`internal bool OnAccepted(AcceptanceParameters acceptanceParameters)`
`584`	`584`	`{`
`585`	`585`	`lock (this.SyncObject)`