Documentation of object.destroy

[Steven Schveighoffer]

On 1/2/18 8:58 AM, Johan Engelen wrote:
> Hi all,
> 
> Link: https://dlang.org/library/object/destroy.html
> 
> The documentation says "Destroys the given object and puts it in an 
> invalid state. " However, this is not (strictly) true. What destroy() 
> does is overwrite the object with T.init (or zeros), and we should 
> explicitly mention that. Also, the documentation states "that it [the 
> object destroyed] no longer references any other objects.", which is 
> wrong as this code shows:

It does something different depending on the type:

Objects: calls rt_finalize on the object, which calls the dtor, deletes 
the monitor, rewrites the init value to the object, and THEN zeroes the 
vtable ptr. This last step makes it inoperable for anyone still holding 
a pointer to the object. This is why I think the docs are written the 
way they are.

Interfaces: If this is a D object, casts to Object and calls destroy on it.

Structs: calls the dtor (if it exists), destroys recursively all the 
data members of the struct, and then initializes the data to it's init 
state.

Everything else: overwrites with the init data. More explicitly, 
destroying a pointer simply sets it to null, and does not destroy what 
it points at.

I would actually recommend ddocing each of the overloads of destroy 
individually instead of lumping them together, identifying what happens 
with each one.

-Steve