Summary of Enumerable.Except(...) is confusing

[mycroes]

The summary of the Enumerable.Except method is as follows:

Produces the set difference of two sequences.

This is amended in the remark:

The set difference of two sets is defined as the members of the first set that don't appear in the second set.

This method returns those elements in first that don't appear in second. It doesn't return those elements in second that don't appear in first. Only unique elements are returned.

The definition of difference in the summary does not align with the mathematical definition of set difference, thus confusing developers that only read the summary and not the remark. This issue is enlarged by the fact that in many circumstances Visual Studio will only show the summary, thus leading to the incorrect assumption that the Except method will produce the mathematical set difference of two sets.

I think the summary would greatly benefit from being precise and accurate without requiring the remark to clarify the implementation.

[dotnet-policy-service]

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

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-linq

[eiriktsarpalis]

The definition of difference in the summary does not align with the mathematical definition of set difference, thus confusing developers that only read the summary and not the remark.

Could you elaborate? As you're pointing out the summary section doesn't contain a definition of set difference. Or is it the case that you disagree with the definition of set difference in the remarks section?

[mycroes]

As you're pointing out the summary section doesn't contain a definition of set difference.

I think we might argue that in this case (Enumerable.X) it'd be better to use terminology that doesn't require additional definitions.

Or is it the case that you disagree with the definition of set difference in the remarks section?

I wasn't agreeing, but after some further reading I noticed this actually is the relative complement, a.k.a. set difference. So I can't really argue about that and I guess my point of mathematical definition doesn't make much sense. I do believe the summary could be better worded to avoid any ambiguation.

[eiriktsarpalis]

As you're pointing out the summary section doesn't contain a definition of set difference.

I think we might argue that in this case (Enumerable.X) it'd be better to use terminology that doesn't require additional definitions.

Not sure I follow. Set difference AKA relative complement is standard terminology for those familiar with sets, but for those that aren't the remarks section contains a simply worded definition. What improvements would you like to see specifically in the documentation?