Document WeakRef type (#48565)

Fixes #26745. Based on suggestion by stevengj (#26745 (comment)).

base/gcutils.jl

@@ -1,5 +1,36 @@
 # This file is a part of Julia. License is MIT: https://julialang.org/license
 
+
+"""
+    WeakRef(x)
+
+`w = WeakRef(x)` constructs a [weak reference](https://en.wikipedia.org/wiki/Weak_reference)
+to the Julia value `x`: although `w` contains a reference to `x`, it does not prevent `x` from being
+garbage collected. `w.value` is either `x` (if `x` has not been garbage-collected yet) or `nothing`
+(if `x` has been garbage-collected).
+
+```jldoctest
+julia> x = "a string"
+"a string"
+
+julia> w = WeakRef(x)
+WeakRef("a string")
+
+julia> GC.gc()
+
+julia> w           # a reference is maintained via `x`
+WeakRef("a string")
+
+julia> x = nothing # clear reference
+
+julia> GC.gc()
+
+julia> w
+WeakRef(nothing)
+```
+"""
+WeakRef
+
 ==(w::WeakRef, v::WeakRef) = isequal(w.value, v.value)
 ==(w::WeakRef, v) = isequal(w.value, v)
 ==(w, v::WeakRef) = isequal(w, v.value)

base/weakkeydict.jl

@@ -12,6 +12,8 @@ referenced in a hash table.
 See [`Dict`](@ref) for further help.  Note, unlike [`Dict`](@ref),
 `WeakKeyDict` does not convert keys on insertion, as this would imply the key
 object was unreferenced anywhere before insertion.
+
+See also [`WeakRef`](@ref).
 """
 mutable struct WeakKeyDict{K,V} <: AbstractDict{K,V}
     ht::Dict{WeakRef,V}

doc/src/base/base.md

@@ -152,6 +152,7 @@ Base.promote
 Base.oftype
 Base.widen
 Base.identity
+Base.WeakRef
 ```
 
 ## Properties of Types