Document auto-shrinking behaviour of `Dictionary`

[Tortar]

This is an important property to me since it allows to solve problems as the one described in https://discourse.julialang.org/t/is-dict-shrinking-feature-planned/68681. Can it be documented as an advantage of Dictionary over Dict? Or can it even be roughly explained what is the heuristic used to do the automatic shrinkage in the docs?

E.g.

julia> using Dictionaries

julia> d = Dictionary(x => x for x in 1:10^6);

julia> Base.summarysize(d)
48777424

julia> for x in 1:10^6 delete!(d, x) end

julia> Base.summarysize(d)
272

julia> d = Dict(x => x for x in 1:10^6);

julia> Base.summarysize(d)
35651768

julia> for x in 1:10^6 delete!(d, x) end

julia> Base.summarysize(d)
35651768

[andyferris]

Yes, I did implement it this way but the reason I didn't advertise this is I wasn't 100% sure whether the underlying Vector actually relinquishes its memory when shrunk. (I have a vague recollection of this being mentioned a long, long time ago and don't know the current story). Does anyone know?