Docs for LazyInitializer.EnsureInitialize<T>(ref T) are wrong

[heaths]

In the documentation for LazyInitializer.EnsureInitialize<T>(ref T target), it states,

In the event that multiple threads access this method concurrently, multiple instances of T may be created, but only one will be stored into target. In such an occurrence, this method will not dispose of the objects that were not stored. If such objects must be disposed, it is up to the caller to determine if an object was not used and to then dispose of the object appropriately.

The code uses Activator.CreateInstance if not already null (guarded by Interlocked.CompareExchanged) but target is only ever returned. The result of Activator.CreateInstance is lost if not placed into target, so callers can never dispose of it if not using an overload that takes a Func<T> and specifically checking for whether it was initialized.

I'm happy to fix the doc comments, but wanted confirmation first that this was actually the intended behavior and that the docs are wrong and should change.

Opened in lieu of dotnet/corefx#42643. I'll are a PR. /cc @danmosemsft

[danmoseley]

Product team actually owns their own API docs, so consider this confirmed 😃