Some Max exception documentation is incorrect

[corranrogue9]

• The documentation here indicates that an ArgumentException will be thrown if no element in source implements IComparable or IComparable. This is not true if source contains only a single element, even if that element does not implement IComparable or IComparable
• The documentation here does not indicate that an ArgumentException will be thrown if some of the elements of source implement IComparable and some of the elements of source do not implement IComparable or IComparable
• The documentation here indicates that null can be returned if TSource is a reference type and source is empty, but it does not indicate that an InvalidOperationException will be thrown if TSource is a value type and source is empty
• The documentation here does not indicate that an ArgumentException can be thrown if none of the projected elements implement IComparable or IComparable, or if only some of them implement IComparable or IComparable
• The documentation here does not indicate that an InvalidOperationException can be thrown if TResult is a value type and source is empty
• The documentation here does not indicate that null will be returned if source is empty
• The documentation here does not indicate that null will be returned if source is empty
• The documentation here does not indicate that null will be returned if source is empty
• The documentation here does not indicate that null will be returned if source is empty

[GrabYourPitchforks]

@mairaw Can you transfer this issue to the docs repo? Thanks! :)

[danmoseley]

@GrabYourPitchforks I think we have rights to do that now.

[danmoseley]

@corranrogue9 any interest in offering a PR for any of this?

[corranrogue9]

@danmosemsft, if you can point me to where the changes need to be made and some guidelines documents, I would be happy to offer a PR

[danmoseley]

@corranrogue9 there is a contributing guide here https://github.com/dotnet/docs/blob/master/CONTRIBUTING.md

To quickly find the file to edit, just click the "edit" button in the top right of the topic. For example for Enumerable.Max: https://docs.microsoft.com/en-us/dotnet/api/system.linq.enumerable.max?view=netframework-4.8#System_Linq_Enumerable_Max__1_System_Collections_Generic_IEnumerable___0__ this goes to https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System.Linq/Enumerable.xml

Hopefully this gets you started!

[carlossanlop]

@corranrogue9 will you get a chance to offer a PR?

cc @eiriktsarpalis @adamsitnik area owners.

[adamsitnik]

@carlossanlop is my understanding correct that it would be the best to wait until you finish your work on backporting the docs to dotnet/runtime source and then add this as triple slash comments to source in dotnet/runtime?

[carlossanlop]

No, you're not blocked to offer a fix in dotnet-api-docs. Just let me know so I make sure my backports include your amends.

[adamsitnik]

after thinking about it for a while I decided to wait until the source code becomes the single source of truth

it's just much easier to find all the throwing public methods and add the annotations in the comments rather than updating the doc

perhaps we could even add an analyser for that? at least for the simple cases like arguments validation throws?