dotnet / dotnet/dotnet-api-docs

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

Open
#12,115 5 comments 0 reactions 0 assignees View on GitHub
area-System.Linq documentation untriaged
Dominant language
C#
Stars
949
Forks
1.7k
Avg merge
3d 27m
Merged PRs (30d)
49

Description

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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.