Documentation of object.destroy

[Johan Engelen]

On Tuesday, 2 January 2018 at 17:16:54 UTC, Steven Schveighoffer 
wrote:
> On 1/2/18 8:58 AM, Johan Engelen wrote:
>> Hi all,
>> 
>> Link: https://dlang.org/library/object/destroy.html

Much obliged to anyone doing the effort of fixing and improving 
the doc.

I think Steven made a nice start. I added some comments below.

> 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.

rt_finalize is an implementation detail and shouldn't be in the 
docs here.
Important to mention the re-init _and_ the obj still being in 
invalid state (vtable is implementation detail and may be left 
out).

> 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 find "does not destroy what it points at" important to mention. 
(perhaps even with an explicit "you have to dereference the 
pointer to destroy what it points at").

Thanks,
Cheers,
   Johan