Add missing APIs doc in ImmutableArrayExtensions #46014
Conversation
|
Tagging subscribers to this area: @eiriktsarpalis Issue DetailsThe The partial API documentation was present in The pull request has initial documentation work, and various missing annotations are added in the APIs. Fix #43854
|
|
|
| @@ -614,6 +641,7 @@ public static T Single<T>(this ImmutableArray<T> immutableArray, Func<T, bool> p | |||
| /// </summary> | |||
| /// <typeparam name="T">The type of element contained by the collection.</typeparam> | |||
| /// <param name="immutableArray"></param> | |||
| /// <exception cref="ThrowNullRefIfNotInitialized">Thrown if the collection is empty.</exception> | |||
There was a problem hiding this comment.
Hi, Make sure you add using statement for namespace for give type in that file!
|
Hi @himanshu8088, our source of truth w.r.t. to API documentation is the https://github.com/dotnet/dotnet-api-docs/ repo. Any improvements should be made there. Note however that @carlossanlop is working towards porting dotnet-api-docs back to source code, so this is subject to change in the future. |
| /// <param name="immutableArray">The immutable array.</param> | ||
| /// <param name="predicate">The predicate.</param> |
There was a problem hiding this comment.
Can you please provide more elaborate descriptions for these two params?
| @@ -94,6 +102,9 @@ public static IEnumerable<T> Where<T>(this ImmutableArray<T> immutableArray, Fun | |||
| /// </summary> | |||
| /// <typeparam name="T">The type of element contained by the collection.</typeparam> | |||
| /// <param name="immutableArray"></param> | |||
| /// <returns> | |||
| /// <c>true</c> if the <paramref name="immutableArray"/> contains any element; otherwise, <c>false</c>. | |||
There was a problem hiding this comment.
Here and elsewhere - Please use <see langword="true" /> and <see langword="false" />:
| /// <c>true</c> if the <paramref name="immutableArray"/> contains any element; otherwise, <c>false</c>. | |
| /// <see langword="true" /> if the <paramref name="immutableArray"/> contains any element; otherwise, <see langword="false" />. |
| /// <param name="immutableArray"></param> | ||
| /// <param name="func"></param> |
There was a problem hiding this comment.
Here and elsewhere - Should not be empty.
| @@ -106,6 +117,9 @@ public static bool Any<T>(this ImmutableArray<T> immutableArray) | |||
| /// <typeparam name="T">The type of element contained by the collection.</typeparam> | |||
| /// <param name="immutableArray"></param> | |||
| @@ -511,6 +536,8 @@ public static T Single<T>(this ImmutableArray<T> immutableArray, Func<T, bool> p | |||
| /// Returns the only element of a sequence that satisfies a specified condition or a default value if no such element exists; this method throws an exception if more than one element satisfies the condition. | |||
| /// </summary> | |||
| /// <typeparam name="T">The type of element contained by the collection.</typeparam> | |||
| /// <param name="immutableArray"></param> | |||
| /// <param name="predicate">The predicate.</param> | |||
There was a problem hiding this comment.
Here and elsewhere - Please provide a more specific/elaborate description.
| @@ -614,6 +641,7 @@ public static T Single<T>(this ImmutableArray<T> immutableArray, Func<T, bool> p | |||
| /// </summary> | |||
| /// <typeparam name="T">The type of element contained by the collection.</typeparam> | |||
| /// <param name="immutableArray"></param> | |||
| /// <exception cref="ThrowNullRefIfNotInitialized">Thrown if the collection is empty.</exception> | |||
There was a problem hiding this comment.
No need to use the word "thrown" in exceptions; it's implied. Instead, you can use:
| /// <exception cref="ThrowNullRefIfNotInitialized">Thrown if the collection is empty.</exception> | |
| /// <exception cref="ThrowNullRefIfNotInitialized">The collection is empty.</exception> |
There was a problem hiding this comment.
The CI failed in all legs due to the following error:
Error CS1574: XML comment has cref attribute 'ThrowNullRefIfNotInitialized' that could not be resolved.
That is because ThrowNullRefIfNotInitialized is not an exception, it's a method that throws an exception. You'll have to inspect that method to see what exception it throws, and use that identifier for the cref.
thanks will accommodate recommended changes |
ericstj
added
the
documentation
carlossanlop
changed the title
|
@himanshu8088 were you planning to resume this PR? |
|
I'm going to close the PR due to lack of activity. @himanshu8088 feel free to reopen when you have the time to work on this again. Thanks. |
ghost
locked as resolved and limited conversation to collaborators
The
param,exception,returns, andtypeparamdoc annotation was missing in various APIsThe partial API documentation was present in
Where,Any,Aggregate,Single,Firstas per the documentation wikiThe pull request has initial documentation work, and various missing annotations are added in the APIs.
This documentation is not complete yet, it can be fixed in further PRs, this is just an initial draft.
Fix #43854