Improve docstrings for union & intersect (#42695)

* docstring for union

* infix

* intersect too

* tweak

* apply suggestions

Author: mcabbott

base/abstractset.jl

@@ -11,30 +11,36 @@ copy!(dst::AbstractSet, src::AbstractSet) = union!(empty!(dst), src)
     union(s, itrs...)
     ∪(s, itrs...)
 
-Construct the union of sets. Maintain order with arrays.
+Construct an object containing all distinct elements from all of the arguments.
 
-See also: [`intersect`](@ref), [`isdisjoint`](@ref), [`vcat`](@ref), [`Iterators.flatten`](@ref).
+The first argument controls what kind of container is returned.
+If this is an array, it maintains the order in which elements first appear.
+
+Unicode `∪` can be typed by writing `\\cup` then pressing tab in the Julia REPL, and in many editors.
+This is an infix operator, allowing `s ∪ itr`.
+
+See also [`unique`](@ref), [`intersect`](@ref), [`isdisjoint`](@ref), [`vcat`](@ref), [`Iterators.flatten`](@ref).
 
 # Examples
 ```jldoctest
-julia> union([1, 2], [3, 4])
-4-element Vector{Int64}:
+julia> union([1, 2], [3])
+3-element Vector{Int64}:
  1
  2
  3
- 4
 
-julia> union([1, 2], [2, 4])
-3-element Vector{Int64}:
- 1
- 2
- 4
+julia> union([4 2 3 4 4], 1:3, 3.0)
+4-element Vector{Float64}:
+ 4.0
+ 2.0
+ 3.0
+ 1.0
 
-julia> union([4, 2], 1:2)
-3-element Vector{Int64}:
- 4
- 2
- 1
+julia> (0, 0.0) ∪ (-0.0, NaN)
+3-element Vector{Real}:
+   0
+  -0.0
+ NaN
 
 julia> union(Set([1, 2]), 2:3)
 Set{Int64} with 3 elements:
@@ -53,14 +59,14 @@ const ∪ = union
 """
     union!(s::Union{AbstractSet,AbstractVector}, itrs...)
 
-Construct the union of passed in sets and overwrite `s` with the result.
+Construct the [`union`](@ref) of passed in sets and overwrite `s` with the result.
 Maintain order with arrays.
 
 # Examples
 ```jldoctest
-julia> a = Set([1, 3, 4, 5]);
+julia> a = Set([3, 4, 5]);
 
-julia> union!(a, 1:2:8);
+julia> union!(a, 1:2:7);
 
 julia> a
 Set{Int64} with 5 elements:
@@ -102,10 +108,15 @@ end
     intersect(s, itrs...)
     ∩(s, itrs...)
 
-Construct the intersection of sets.
-Maintain order with arrays.
+Construct the set containing those elements which appear in all of the arguments.
+
+The first argument controls what kind of container is returned.
+If this is an array, it maintains the order in which elements first appear.
 
-See also: [`setdiff`](@ref), [`isdisjoint`](@ref), [`issubset`](@ref Base.issubset), [`issetequal`](@ref).
+Unicode `∩` can be typed by writing `\\cap` then pressing tab in the Julia REPL, and in many editors.
+This is an infix operator, allowing `s ∩ itr`.
+
+See also [`setdiff`](@ref), [`isdisjoint`](@ref), [`issubset`](@ref Base.issubset), [`issetequal`](@ref).
 
 !!! compat "Julia 1.8"
     As of Julia 1.8 intersect returns a result with the eltype of the
@@ -117,14 +128,21 @@ julia> intersect([1, 2, 3], [3, 4, 5])
 1-element Vector{Int64}:
  3
 
-julia> intersect([1, 4, 4, 5, 6], [4, 6, 6, 7, 8])
+julia> intersect([1, 4, 4, 5, 6], [6, 4, 6, 7, 8])
 2-element Vector{Int64}:
  4
  6
 
-julia> intersect(Set([1, 2]), BitSet([2, 3]))
-Set{Int64} with 1 element:
-  2
+julia> intersect(1:16, 7:99)
+7:16
+
+julia> (0, 0.0) ∩ (-0.0, 0)
+1-element Vector{Real}:
+ 0
+
+julia> intersect(Set([1, 2]), BitSet([2, 3]), 1.0:10.0)
+Set{Float64} with 1 element:
+  2.0
 ```
 """
 function intersect(s::AbstractSet, itr, itrs...)