Seq.except xml doc description / tooltip info can be improved
- Dominant language
- F#
- Stars
- 4.3k
- Forks
- 876
- Avg merge
- 4d 11h
- Merged PRs (30d)
- 131
Description
For one reason or another, I always thought that `Seq.except` takes a sequence and removes all elements from it that are in the `itemsToExclude` sequence. The tooltip says this:
> Returns a new sequence with the distinct elements of the second sequence which do not appear in the first sequence, using generic hash and equality comparisons to compare values.
This isn't wrong, but it is fairly easy to read over the "with the **distinct** elements of the second sequence" bit. This function actually does a set-except operation. Basically, it makes the sequence distinct (i.e., drops all elements that are hashset-equal to another element), plus it removes those elements that are in the `itemsToExclude` sequence.
```f#
> [1;2;2;3;1] |> Seq.except [2];;
val it: seq = seq [1; 3]
> [1;2;2;3;1] |> Seq.except Seq.empty;;
val it: seq = seq [1; 2; 3]
```
Since sequences _are not sets_, this was a bit surprising to me when I naively started implementing this same operation in `TaskSeq`. Just because it is not a set, something like `exceptDistinct` seems to make more sense (also, it seems like a "remove all elements that are in sequence X from sequence Y" does not exist for `seq`).
Anyway, not suggesting a change or wanting to add a new function. Here's an attempt at a better wording, but other suggestions welcome before I'd open a PR to do so.
### Suggestion:
```xml
Does a set-except operation on both sequences, returning a new sequence based on
after removing duplicates and any element that also appears
in , using generic hash and equality comparisons to
compare values.
```
We should probably also update the example given in the docs to make this particular behavior clear.
Contributor guide
Assessment
This issue has not been assessed yet.