Skip to content

Port documentation for .NET 7.0 Preview2 #7889

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.

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

Merged
merged 34 commits into from
Mar 31, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
34 commits
Select commit Hold shift + click to select a range
f403e1a
Microsoft.Extensions.DiagnosticAdapter.Internal
carlossanlop Mar 28, 2022
a46279e
Microsoft.Extensions.Logging.AzureAppServices.Internal
carlossanlop Mar 28, 2022
b9e0711
Microsoft.Extensions.Logging.Console
carlossanlop Mar 28, 2022
ed68b26
Microsoft.Extensions.Logging.Filter.Internal
carlossanlop Mar 28, 2022
9a71172
Microsoft.Extensions.Logging.TraceSource
carlossanlop Mar 28, 2022
e0fb2e5
Microsoft.Extensions.Primitives
carlossanlop Mar 28, 2022
007d98d
System
carlossanlop Mar 28, 2022
901086b
System.Collections.Concurrent
carlossanlop Mar 28, 2022
e236e2a
System.Collections.Immutable
carlossanlop Mar 28, 2022
7b63399
System.Collections.Specialized
carlossanlop Mar 28, 2022
b52ba44
System.ComponentModel.Composition.ReflectionModel
carlossanlop Mar 28, 2022
b1b2bda
System.ComponentModel.Design.Serialization
carlossanlop Mar 28, 2022
92802bf
System.Data.SqlTypes
carlossanlop Mar 28, 2022
41436c5
System.Diagnostics
carlossanlop Mar 28, 2022
34fc34d
System.Diagnostics.CodeAnalysis
carlossanlop Mar 28, 2022
a73cf72
System.Diagnostics.Metrics
carlossanlop Mar 28, 2022
983d213
System.Drawing
carlossanlop Mar 28, 2022
d9e3998
System.IO
carlossanlop Mar 28, 2022
ebb3d27
System.IO.Compression
carlossanlop Mar 28, 2022
e6c12ef
System.Linq
carlossanlop Mar 28, 2022
6b9fd7f
System.Net.Sockets
carlossanlop Mar 28, 2022
12dacd2
System.Reflection
carlossanlop Mar 28, 2022
8e88b82
System.Runtime.CompilerServices
carlossanlop Mar 28, 2022
b500534
System.Runtime.InteropServices
carlossanlop Mar 28, 2022
1139b2f
System.Runtime.Intrinsics.Arm
carlossanlop Mar 28, 2022
a41ce85
System.Security.Cryptography
carlossanlop Mar 28, 2022
01cfbe3
System.Security.Cryptography.Cose
carlossanlop Mar 28, 2022
4dce592
System.Text.RegularExpressions
carlossanlop Mar 28, 2022
837f031
System.Transactions
carlossanlop Mar 28, 2022
9cdc64d
System.Web.DynamicData
carlossanlop Mar 28, 2022
35682e3
Suggestions by gewarren
carlossanlop Mar 29, 2022
19711be
suggestions by gewarren
carlossanlop Mar 30, 2022
72e9a27
Apply suggestions from code review
gewarren Mar 31, 2022
3887d09
Update xml/System.Diagnostics.Metrics/ObservableUpDownCounter`1.xml
gewarren Mar 31, 2022
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@
</TypeParameters>
<Parameters />
<Docs>
<typeparam name="T">To be added.</typeparam>
<typeparam name="T">The type of the underlying object.</typeparam>
<summary>Unwraps the underlying object and performs a cast to <typeparamref name="T" />.</summary>
<returns>The underlying object.</returns>
<remarks>To be added.</remarks>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -82,7 +82,7 @@
<Parameter Name="obj" Type="System.Object" />
</Parameters>
<Docs>
<typeparam name="TProxy">To be added.</typeparam>
<typeparam name="TProxy">The type of the proxy to create.</typeparam>
<param name="obj">The object to wrap in a proxy.</param>
<summary>Creates a proxy object that is assignable to type <typeparamref name="TProxy" />.</summary>
<returns>A proxy object, or <paramref name="obj" /> if a proxy is not needed.</returns>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -76,7 +76,7 @@
<Parameter Name="state" Type="TState" />
</Parameters>
<Docs>
<typeparam name="TState">To be added.</typeparam>
<typeparam name="TState">The type of the state to begin scope for.</typeparam>
<param name="state">The identifier for the scope.</param>
<summary>Begins a logical operation scope.</summary>
<returns>A disposable object that ends the logical operation scope on dispose.</returns>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@
<Parameter Name="state" Type="TState" />
</Parameters>
<Docs>
<typeparam name="TState">To be added.</typeparam>
<typeparam name="TState">The type of the state to begin scope for.</typeparam>
<param name="state">The identifier for the scope.</param>
<summary>Begins a logical operation scope.</summary>
<returns>A disposable object that ends the logical operation scope on dispose.</returns>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@
<Parameter Name="state" Type="TState" />
</Parameters>
<Docs>
<typeparam name="TState">To be added.</typeparam>
<typeparam name="TState">The type of the state to begin scope for.</typeparam>
<param name="state">The identifier for the scope.</param>
<summary>Begins a logical operation scope.</summary>
<returns>An <see cref="T:System.IDisposable" /> that ends the logical operation scope on dispose.</returns>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@
<Parameter Name="state" Type="TState" />
</Parameters>
<Docs>
<typeparam name="TState">To be added.</typeparam>
<typeparam name="TState">The type of the state to begin scope for.</typeparam>
<param name="state">The identifier for the scope.</param>
<summary>Begins a logical operation scope.</summary>
<returns>A disposable object that ends the logical operation scope on dispose.</returns>
Expand Down
6 changes: 3 additions & 3 deletions xml/Microsoft.Extensions.Primitives/StringSegment.xml
Original file line number Diff line number Diff line change
Expand Up @@ -442,11 +442,11 @@
</Parameter>
</Parameters>
<Docs>
<param name="obj">To be added.</param>
<param name="obj">An object to compare with this object.</param>
<summary>Indicates whether the current object is equal to another object of the same type.</summary>
<returns>To be added.</returns>
<returns>
<see langword="true" /> if the current object is equal to <paramref name="obj" />; otherwise, <see langword="false" />.</returns>
<remarks>To be added.</remarks>
<inheritdoc />
</Docs>
</Member>
<Member MemberName="Equals">
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -1404,6 +1404,7 @@ This member is an explicit interface member implementation. It can be used only
</remarks>
<exception cref="T:System.ObjectDisposedException">The <see cref="T:System.Collections.Concurrent.BlockingCollection`1" /> has been disposed.</exception>
<exception cref="T:System.InvalidOperationException">The underlying collection was modified outside of this <see cref="T:System.Collections.Concurrent.BlockingCollection`1" /> instance, or the <see cref="T:System.Collections.Concurrent.BlockingCollection`1" /> is empty and the collection has been marked as complete for adding.</exception>
<exception cref="T:System.OperationCanceledException">The <see cref="T:System.Collections.Concurrent.BlockingCollection`1" /> is empty and has been marked as complete with regards to additions.</exception>
<related type="Article" href="/dotnet/standard/collections/thread-safe/">Thread-Safe Collections</related>
<related type="Article" href="/dotnet/standard/collections/thread-safe/blockingcollection-overview">BlockingCollection Overview</related>
</Docs>
Expand Down
32 changes: 16 additions & 16 deletions xml/System.Collections.Immutable/ImmutableArray.xml
Original file line number Diff line number Diff line change
Expand Up @@ -289,10 +289,10 @@
<Parameter Name="items" Type="System.ReadOnlySpan&lt;T&gt;" Index="0" FrameworkAlternate="net-7.0" />
</Parameters>
<Docs>
<typeparam name="T">To be added.</typeparam>
<param name="items">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<typeparam name="T">The type of element stored in the array.</typeparam>
<param name="items">The elements to store in the array.</param>
<summary>Creates an <see cref="T:System.Collections.Immutable.ImmutableArray`1" /> with the specified elements.</summary>
<returns>An immutable array containing the specified items.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -318,10 +318,10 @@
<Parameter Name="items" Type="System.Span&lt;T&gt;" Index="0" FrameworkAlternate="net-7.0" />
</Parameters>
<Docs>
<typeparam name="T">To be added.</typeparam>
<param name="items">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<typeparam name="T">The type of element stored in the array.</typeparam>
<param name="items">The elements to store in the array.</param>
<summary>Creates an <see cref="T:System.Collections.Immutable.ImmutableArray`1" /> with the specified elements.</summary>
<returns>An immutable array containing the specified items.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -976,10 +976,10 @@ This overload allows helper methods or custom builder classes to efficiently avo
<Parameter Name="items" Type="System.ReadOnlySpan&lt;T&gt;" Index="0" FrameworkAlternate="net-7.0" RefType="this" />
</Parameters>
<Docs>
<typeparam name="T">To be added.</typeparam>
<param name="items">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<typeparam name="T">The type of element in the list.</typeparam>
<param name="items">The elements to store in the array.</param>
<summary>Produce an immutable array of contents from specified elements.</summary>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This one is different because it's an extension method. So is this more accurate?

Suggested change
<summary>Produce an immutable array of contents from specified elements.</summary>
<summary>Converts the span to an immutable array.</summary>

Copy link
Contributor Author

@carlossanlop carlossanlop Mar 29, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dotnet/area-system-collections thoughts?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see any specific guidance for the this extension method parameter in the writing guidelines wiki. It just seems weird to refer to it as "the specified elements" when in most cases, you aren't really "specifying" them. You're calling a method on them.

Anyway, I don't think this is super important, so I'm fine if you want to leave it as-is.

<returns>An immutable array containing the items in the span.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -1005,10 +1005,10 @@ This overload allows helper methods or custom builder classes to efficiently avo
<Parameter Name="items" Type="System.Span&lt;T&gt;" Index="0" FrameworkAlternate="net-7.0" RefType="this" />
</Parameters>
<Docs>
<typeparam name="T">To be added.</typeparam>
<param name="items">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<typeparam name="T">The type of element in the list.</typeparam>
<param name="items">The elements to store in the array.</param>
<summary>Converts the span to an immutable array.</summary>
<returns>An immutable array containing the items in the span.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
12 changes: 6 additions & 6 deletions xml/System.Collections.Immutable/ImmutableArray`1+Builder.xml
Original file line number Diff line number Diff line change
Expand Up @@ -216,8 +216,8 @@
<Parameter Name="items" Type="System.ReadOnlySpan&lt;T&gt;" Index="0" FrameworkAlternate="net-7.0" />
</Parameters>
<Docs>
<param name="items">To be added.</param>
<summary>To be added.</summary>
<param name="items">The items to add at the end of the array.</param>
<summary>Adds the specified items to the end of the array.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -440,8 +440,8 @@
</Parameters>
<Docs>
<typeparam name="TDerived">To be added.</typeparam>
<param name="items">To be added.</param>
<summary>To be added.</summary>
<param name="items">The items to add at the end of the array.</param>
<summary>Adds the specified items to the end of the array.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -606,8 +606,8 @@
<Parameter Name="destination" Type="System.Span&lt;T&gt;" Index="0" FrameworkAlternate="net-7.0" />
</Parameters>
<Docs>
<param name="destination">To be added.</param>
<summary>To be added.</summary>
<param name="destination">The <see cref="T:System.Span`1" /> to copy to.</param>
<summary>Copies the current contents to the specified <see cref="T:System.Span`1" />.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
70 changes: 35 additions & 35 deletions xml/System.Collections.Immutable/ImmutableArray`1.xml
Original file line number Diff line number Diff line change
Expand Up @@ -233,9 +233,9 @@
<Parameter Name="items" Type="System.ReadOnlySpan&lt;T&gt;" Index="0" FrameworkAlternate="net-7.0" />
</Parameters>
<Docs>
<param name="items">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="items">The values to add.</param>
<summary>Adds the specified values to this list.</summary>
<returns>A new list with the elements added.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -265,9 +265,9 @@
</Parameter>
</Parameters>
<Docs>
<param name="items">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="items">The values to add.</param>
<summary>Adds the specified values to this list.</summary>
<returns>A new list with the elements added.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -390,9 +390,9 @@
<Parameter Name="range" Type="System.Range" Index="0" FrameworkAlternate="net-7.0" />
</Parameters>
<Docs>
<param name="range">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="range">A range in the current <see cref="T:System.Collections.Immutable.ImmutableArray`1" />.</param>
<summary>Creates a span over the portion of the current <see cref="T:System.Collections.Immutable.ImmutableArray`1" /> based on the specified <paramref name="range" />.</summary>
<returns>A span representation of the <see cref="T:System.Collections.Immutable.ImmutableArray`1" />.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -416,10 +416,10 @@
<Parameter Name="length" Type="System.Int32" Index="1" FrameworkAlternate="net-7.0" />
</Parameters>
<Docs>
<param name="start">To be added.</param>
<param name="length">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="start">The index at which to begin the span.</param>
<param name="length">The number of items in the span.</param>
<summary>Creates a <see cref="T:System.ReadOnlySpan`1" /> over the portion of the current <see cref="T:System.Collections.Immutable.ImmutableArray`1" />, beginning at a specified position for a specified length.</summary>
<returns>The <see cref="T:System.ReadOnlySpan`1" /> representation of the <see cref="T:System.Collections.Immutable.ImmutableArray`1" />.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -601,8 +601,8 @@
<Parameter Name="destination" Type="System.Span&lt;T&gt;" Index="0" FrameworkAlternate="net-7.0" />
</Parameters>
<Docs>
<param name="destination">To be added.</param>
<summary>To be added.</summary>
<param name="destination">The <see cref="T:System.Span`1" /> that is the destination of the elements copied from current <see cref="T:System.Collections.Immutable.ImmutableArray`1" />.</param>
<summary>Copies the elements of current <see cref="T:System.Collections.Immutable.ImmutableArray`1" /> to a <see cref="T:System.Span`1" />.</summary>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -1210,10 +1210,10 @@
<Parameter Name="items" Type="System.ReadOnlySpan&lt;T&gt;" Index="1" FrameworkAlternate="net-7.0" />
</Parameters>
<Docs>
<param name="index">To be added.</param>
<param name="items">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="index">The index at which to insert the value.</param>
<param name="items">The elements to insert.</param>
<summary>Inserts the specified values at the specified index.</summary>
<returns>The new immutable collection.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -1237,10 +1237,10 @@
<Parameter Name="items" Type="T[]" Index="1" FrameworkAlternate="net-7.0" />
</Parameters>
<Docs>
<param name="index">To be added.</param>
<param name="items">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="index">The index at which to insert the value.</param>
<param name="items">The elements to insert.</param>
<summary>Inserts the specified values at the specified index.</summary>
<returns>The new immutable collection.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -2137,10 +2137,10 @@
<Parameter Name="equalityComparer" Type="System.Collections.Generic.IEqualityComparer&lt;T&gt;" Index="1" FrameworkAlternate="net-7.0" />
</Parameters>
<Docs>
<param name="items">To be added.</param>
<param name="equalityComparer">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="items">The items to remove if matches are found in this list.</param>
<param name="equalityComparer">The equality comparer to use in the search.</param>
<summary>Removes the specified values from this list.</summary>
<returns>A new list with the elements removed.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand All @@ -2163,10 +2163,10 @@
<Parameter Name="equalityComparer" Type="System.Collections.Generic.IEqualityComparer&lt;T&gt;" Index="1" FrameworkAlternate="net-7.0" />
</Parameters>
<Docs>
<param name="items">To be added.</param>
<param name="equalityComparer">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="items">The items to remove if matches are found in this list.</param>
<param name="equalityComparer">The equality comparer to use in the search.</param>
<summary>Removes the specified values from this list.</summary>
<returns>A new list with the elements removed.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down Expand Up @@ -2305,10 +2305,10 @@
<Parameter Name="length" Type="System.Int32" Index="1" FrameworkAlternate="net-7.0" />
</Parameters>
<Docs>
<param name="start">To be added.</param>
<param name="length">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="start">The index at which to begin this slice.</param>
<param name="length">The desired length for the slice.</param>
<summary>Forms a slice out of the current <see cref="T:System.Collections.Immutable.ImmutableArray`1" /> starting at a specified index for a specified length.</summary>
<returns>An <see cref="T:System.Collections.Immutable.ImmutableArray`1" /> that consists of <paramref name="length" /> elements from the current <see cref="T:System.Collections.Immutable.ImmutableArray`1" />, starting at <paramref name="start" />.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
7 changes: 4 additions & 3 deletions xml/System.Collections.Specialized/BitVector32.xml
Original file line number Diff line number Diff line change
Expand Up @@ -565,9 +565,10 @@
<Parameter Name="other" Type="System.Collections.Specialized.BitVector32" Index="0" FrameworkAlternate="net-7.0" />
</Parameters>
<Docs>
<param name="other">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="other">An instance to compare with this instance.</param>
<summary>Indicates whether the current instance is equal to another instance of the same type.</summary>
<returns>
<see langword="true" /> if the current instance is equal to the other instance; otherwise, <see langword="false" />.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -137,9 +137,10 @@
<Parameter Name="other" Type="System.ComponentModel.Composition.ReflectionModel.LazyMemberInfo" Index="0" FrameworkAlternate="dotnet-plat-ext-7.0" />
</Parameters>
<Docs>
<param name="other">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="other">An instance to compare with this instance.</param>
<summary>Indicates whether the current instance is equal to another instance of the same type.</summary>
<returns>
<see langword="true" /> if the current instance is equal to the other instance; otherwise, <see langword="false" />.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -175,7 +175,7 @@
</Parameters>
<Docs>
<param name="other">To be added.</param>
<summary>To be added.</summary>
<summary>Infrastructure support to make this a first class struct</summary>
Copy link
Contributor Author

@carlossanlop carlossanlop Mar 28, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems like an old change, but I'm not sure why we're capturing it just now. @gewarren did this assembly exist before in dotnet-api-docs?

Also, @dotnet/area-system-componentmodel can you please provide a more meaningful summary?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see there have been some recent modifications to the file, even though most of the Equals or == overloads have been there for a few years.

@stephentoub are we ok with keeping that summary?

https://github.com/dotnet/runtime/blame/dbef8db7c4e1d20dab771f234441c91770f66a58/src/libraries/System.ComponentModel.TypeConverter/src/System/ComponentModel/Design/Serialization/MemberRelationshipService.cs#L221

<returns>To be added.</returns>
<remarks>To be added.</remarks>
</Docs>
Expand Down
7 changes: 4 additions & 3 deletions xml/System.Data.SqlTypes/SqlBinary.xml
Original file line number Diff line number Diff line change
Expand Up @@ -420,9 +420,10 @@
<Parameter Name="other" Type="System.Data.SqlTypes.SqlBinary" Index="0" FrameworkAlternate="net-7.0" />
</Parameters>
<Docs>
<param name="other">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="other">An instance to compare with this instance.</param>
<summary>Indicates whether the current instance is equal to another instance of the same type.</summary>
<returns>
<see langword="true" /> if the current instance is equal to the other instance; otherwise, <see langword="false" />.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
7 changes: 4 additions & 3 deletions xml/System.Data.SqlTypes/SqlBoolean.xml
Original file line number Diff line number Diff line change
Expand Up @@ -490,9 +490,10 @@
<Parameter Name="other" Type="System.Data.SqlTypes.SqlBoolean" Index="0" FrameworkAlternate="net-7.0" />
</Parameters>
<Docs>
<param name="other">To be added.</param>
<summary>To be added.</summary>
<returns>To be added.</returns>
<param name="other">An instance to compare with this instance.</param>
<summary>Indicates whether the current instance is equal to another instance of the same type.</summary>
<returns>
<see langword="true" /> if the current instance is equal to the other instance; otherwise, <see langword="false" />.</returns>
<remarks>To be added.</remarks>
</Docs>
</Member>
Expand Down
Loading