Mention computation of type in docstring

base/set.jl

@@ -682,6 +682,14 @@ Return a copy of collection `A` where, for each pair `old=>new` in `old_new`,
 all occurrences of `old` are replaced by `new`.
 Equality is determined using [`isequal`](@ref).
 If `count` is specified, then replace at most `count` occurrences in total.
+
+The element type of the result is chosen using promotion (see [`promote_type`](@ref))
+based on the element type of `A` and on the types of the `new` values in pairs.
+If `count` is omitted and the element type of `A` is a `Union`, the element type
+of the result will not include singleton types which are replaced with values of
+a different type: for example, `Union{T,Missing}` will become `T` if `missing` is
+replaced.
+
 See also [`replace!`](@ref).
 
 # Examples
@@ -692,6 +700,11 @@ julia> replace([1, 2, 1, 3], 1=>0, 2=>4, count=2)
  4
  1
  3
+
+julia> replace([1, missing], missing=>0)
+2-element Array{Int64,1}:
+ 1
+ 0
 ```
 """
 function replace(A, old_new::Pair...; count::Union{Integer,Nothing}=nothing)