Expand documentation of Set (#45416)

Hash sets have properties that can be counter-intuitive to people not familiar
with computer science: They provide constant-time membership testing, are unordered,
and deduplicate their elements as determined by `isequal` and `hash`.

This commit expands the documentation of `Set` to mention the above properties,
and also that it is a subtype of `AbstractSet`.

base/set.jl

@@ -1,5 +1,41 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
+"""
+ Set{T} <: AbstractSet{T}
+
+`Set`s are mutable containers that provide fast membership testing.
+
+`Set`s have efficient implementations of set operations such as `in`, `union` and `intersect`.
+Elements in a `Set` are unique, as determined by the elements' definition of `isequal`.
+The order of elements in a `Set` is an implementation detail and cannot be relied on.
+
+See also: [`AbstractSet`](@ref), [`BitSet`](@ref), [`Dict`](@ref),
+[`push!`](@ref), [`empty!`](@ref), [`union!`](@ref), [`in`](@ref), [`isequal`](@ref)
+
+# Examples
+```jldoctest filter = r"^\\S.+"
+julia> s = Set("aaBca")
+Set{Char} with 3 elements:
+ 'a'
+ 'c'
+ 'B'
+
+julia> push!(s, 'b')
+Set{Char} with 4 elements:
+ 'a'
+ 'c'
+ 'b'
+ 'B'
+
+julia> s = Set([NaN, 0.0, 1.0, 2.0]);
+
+julia> -0.0 in s # isequal(0.0, -0.0) is false
+false
+
+julia> NaN in s # isequal(NaN, NaN) is true
+true
+```
+"""
 struct Set{T} <: AbstractSet{T}
  dict::Dict{T,Nothing}
 
@@ -19,17 +55,7 @@ function Set{T}(s::KeySet{T, <:Dict{T}}) where {T}
  _Set(Dict{T,Nothing}(slots, keys, vals, d.ndel, d.count, d.age, d.idxfloor, d.maxprobe))
 end
 
-"""
- Set([itr])
-
-Construct a [`Set`](@ref) of the values generated by the given iterable object, or an
-empty set. Should be used instead of [`BitSet`](@ref) for sparse integer sets, or
-for sets of arbitrary objects.
-
-See also: [`push!`](@ref), [`empty!`](@ref), [`union!`](@ref), [`in`](@ref).
-"""
 Set(itr) = _Set(itr, IteratorEltype(itr))
-
 _Set(itr, ::HasEltype) = Set{eltype(itr)}(itr)
 
 function _Set(itr, ::EltypeUnknown)