Port System.Collections docs for .NET 9 APIs

Below is the list of APIs that still show up as undocumented in dotnet-api-docs and were introduced in .NET 9.

Full porting instructions can be found in the main issue.

This task needs to be finished the day before the RC2 snap (September 15th).

RC1 APIs as of 2024/10/01: #105976 (comment)

Tagging subscribers to this area: @dotnet/area-system-collections
See info in area-owners.md if you want to be subscribed.

Here's a PR that ports some that we missed in the first pass: dotnet/dotnet-api-docs#10209

P7 Undoc APIs as of 08/20:

Summary	Parameters	TypeParameters	ReturnValue	API
Missing	Missing	Missing	Missing	M:System.Collections.Concurrent.ConcurrentDictionary2.TryGetAlternateLookup1(System.Collections.Concurrent.ConcurrentDictionary2.AlternateLookup{0,1,0}@)
Present	NA	Missing	NA	T:System.Collections.Concurrent.ConcurrentDictionary2.AlternateLookup1
Present	Present	NA	Missing	M:System.Collections.Concurrent.ConcurrentDictionary2.AlternateLookup1.TryGetValue(2,0@,1@)
Present	Present	NA	Missing	M:System.Collections.Concurrent.ConcurrentDictionary2.AlternateLookup1.TryGetValue(2,1@)
Missing	Missing	Missing	Missing	M:System.Collections.Frozen.FrozenDictionary2.TryGetAlternateLookup1(System.Collections.Frozen.FrozenDictionary2.AlternateLookup{0,1,0}@)
Present	NA	Missing	NA	T:System.Collections.Frozen.FrozenDictionary2.AlternateLookup1
Present	Present	NA	Missing	M:System.Collections.Frozen.FrozenDictionary2.AlternateLookup1.TryGetValue(2,1@)
Missing	Missing	Missing	Missing	M:System.Collections.Frozen.FrozenSet1.TryGetAlternateLookup1(System.Collections.Frozen.FrozenSet1.AlternateLookup{0,0}@)
Present	NA	Missing	NA	T:System.Collections.Frozen.FrozenSet1.AlternateLookup1
Present	NA	Missing	NA	T:System.Collections.Generic.Dictionary2.AlternateLookup1
Present	Present	NA	Missing	M:System.Collections.Generic.Dictionary2.AlternateLookup1.TryGetValue(2,1@)
Present	Present	NA	Missing	M:System.Collections.Generic.Dictionary2.AlternateLookup1.TryGetValue(2,0@,1@)
Present	NA	Missing	NA	T:System.Collections.Generic.HashSet1.AlternateLookup1
Present	Missing	NA	Present	M:System.Collections.Generic.OrderedDictionary2.KeyCollection.Contains(0)

@carlossanlop

With the exception of all the TryGetValue methods, everything else in this table appears to be documented in source, for example the entry in the first row:

runtime/src/libraries/System.Collections.Concurrent/src/System/Collections/Concurrent/ConcurrentDictionary.cs

Lines 247 to 258 in d756692

    
           /// <summary> 
        
           /// Gets an instance of a type that may be used to perform operations on a <see cref="ConcurrentDictionary{TKey, TValue}"/> 
        
           /// using a <typeparamref name="TAlternateKey"/> as a key instead of a <typeparamref name="TKey"/>. 
        
           /// </summary> 
        
           /// <typeparam name="TAlternateKey">The alternate type of a key for performing lookups.</typeparam> 
        
           /// <param name="lookup">The created lookup instance when the method returns true, or a default instance that should not be used if the method returns false.</param> 
        
           /// <returns>true if a lookup could be created; otherwise, false.</returns> 
        
           /// <remarks> 
        
           /// This instance must be using a comparer that implements <see cref="IAlternateEqualityComparer{TAlternateKey, TKey}"/> with 
        
           /// <typeparamref name="TAlternateKey"/> and <typeparamref name="TKey"/>. If it doesn't, the method will return false. 
        
           /// </remarks> 
        
           public bool TryGetAlternateLookup<TAlternateKey>(out AlternateLookup<TAlternateKey> lookup) where TAlternateKey : notnull, allows ref struct

Running the tool again locally seems to be skipping over these missing docs as well. @carlossanlop any suggestions or should I just port the missing docs manually?

@carlossanlop

Running the tool again locally seems to be skipping over these missing docs as well. @carlossanlop any suggestions or should I just port the missing docs manually?

That's not good. What command were you using? Do any of the APIs live under System.Private.CoreLib?

I followed the instructions from the parent issue. Some APIs are SPCL but others are regular libs so I don't think it's related.

@eiriktsarpalis

Reopening as there were new APIs introduced in RC1. @eiriktsarpalis

API	Summary	Parameters	TypeParameters	ReturnValue
T:System.Collections.Concurrent.ConcurrentDictionary2.AlternateLookup1	Present	NA	Missing	NA
T:System.Collections.Frozen.FrozenDictionary2.AlternateLookup1	Present	NA	Missing	NA
T:System.Collections.Frozen.FrozenSet1.AlternateLookup1	Present	NA	Missing	NA
M:System.Collections.Generic.Dictionary2.GetAlternateLookup1	Missing	NA	Missing	Missing
M:System.Collections.Generic.Dictionary2.TryGetAlternateLookup1(System.Collections.Generic.Dictionary2.AlternateLookup{0,1,0}@)	Missing	Missing	Missing	Missing
T:System.Collections.Generic.Dictionary2.AlternateLookup1	Present	NA	Missing	NA
M:System.Collections.Generic.Dictionary2.AlternateLookup1.TryGetValue(2,0@,1@)	Present	Present	NA	Missing
M:System.Collections.Generic.Dictionary2.AlternateLookup1.TryGetValue(2,1@)	Present	Present	NA	Missing
M:System.Collections.Generic.HashSet1.GetAlternateLookup1	Missing	NA	Missing	Missing
M:System.Collections.Generic.HashSet1.TryGetAlternateLookup1(System.Collections.Generic.HashSet1.AlternateLookup{0,0}@)	Missing	Missing	Missing	Missing
T:System.Collections.Generic.HashSet1.AlternateLookup1	Present	NA	Missing	NA

@buyaa-n

Adding @buyaa-n for some load-balancing.

The missing APIs are documented in source. I re-ran the porting tool and hit the same issue I reported in #105976 (comment). At the time I had hand-ported the missing docs to dotnet-api-docs in dotnet/dotnet-api-docs#10338 but the APIs got moved to a different location in RC1. Unless somebody else picks this up, I'll look at re-hand porting the docs later in the week or next week but ideally this should be solved in the tooling.

Navigation Menu

Repository navigation

Port System.Collections docs for .NET 9 APIs #105976

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	/// <summary>
	/// Gets an instance of a type that may be used to perform operations on a <see cref="ConcurrentDictionary{TKey, TValue}"/>
	/// using a <typeparamref name="TAlternateKey"/> as a key instead of a <typeparamref name="TKey"/>.
	/// </summary>
	/// <typeparam name="TAlternateKey">The alternate type of a key for performing lookups.</typeparam>
	/// <param name="lookup">The created lookup instance when the method returns true, or a default instance that should not be used if the method returns false.</param>
	/// <returns>true if a lookup could be created; otherwise, false.</returns>
	/// <remarks>
	/// This instance must be using a comparer that implements <see cref="IAlternateEqualityComparer{TAlternateKey, TKey}"/> with
	/// <typeparamref name="TAlternateKey"/> and <typeparamref name="TKey"/>. If it doesn't, the method will return false.
	/// </remarks>
	public bool TryGetAlternateLookup<TAlternateKey>(out AlternateLookup<TAlternateKey> lookup) where TAlternateKey : notnull, allows ref struct

Port System.Collections docs for .NET 9 APIs #105976

Description

Activity

dotnet-policy-service commented on Aug 5, 2024

carlossanlop commented on Aug 6, 2024

carlossanlop commented on Aug 21, 2024

eiriktsarpalis commented on Aug 29, 2024

carlossanlop commented on Aug 29, 2024

eiriktsarpalis commented on Aug 29, 2024

carlossanlop commented on Oct 1, 2024

jeffhandley commented on Oct 8, 2024

eiriktsarpalis commented on Oct 8, 2024

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions