I would agree that this documentation needs rewording. After reading the line over a few times in good faith, I still have no clue what the author was intending to imply. Whatever the case, it’s deceptive, unclear, and should absolutely be changed.
For all practical purposes, I think the observed behavior here makes sense, if developers think of the Instance as merely a distributed interface, and not a direct representation of the underlying object itself. This interface needs to preserve the object (otherwise it can’t make changes), but it itself does not need to be maintained by anything but the user’s code.
I would also note that not all of the workarounds for weakly referencing Instances are too unwieldly. Sure, over the years, I’ve certainly seen a fair share of scripters get worked up about this issue, and write massive several hundred line solutions; but circumstantially, there’s a far simpler approach which has been good and feasible since the dawn of this problem: abstraction.
As an example, here’s a basic implementation of a method I designed a few years back (though there’s no shortage of elegant means for accomplishing the same feat through similar reasoning)
Example
local WeakTable = setmetatable({}, {__mode = 'v'})
local function CreateWeakInstanceReference(Object, AssociatedData)
local SubstituteReference = Instance.new("Folder")
SubstituteReference.Name = "ReferentialSubstitution"
SubstituteReference.Parent = Object
WeakTable[SubstituteReference] = AssociatedData
Object:GetAttributeChangedSignal("ReferenceKeeper"):Connect(function()
return AssociatedData
end)
end
Here, I use a connection in order to associate some data (a complex object which isn’t an Instance) in a one-directional referential relationship with the underlying instance itself. This way, the instance preserves the object until it’s picked up by GC; meaning I can use this data as a value in a weak table, and that entry will vanish some time after the instance is collected. For the key, I create a child of that object, so that I can momentarily access the Instance I’m abstracting at any time, by grabbing the key’s .Parent
(the abstracted instance itself cannot be used, as that would create a cyclic reference). Since only the values in this table are weak, the key won’t vanish until the entry is removed when the value is GCd; which, due to the relationship established by the connection, won’t happen until after the abstracted instance is collected.