Documentation of object.destroy

[Johan Engelen]

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:

```
__gshared int global;
struct S {
     int* pint = &global;
}
void main() {
     S s;
     int i;
     s.pint = &i;
     assert(s.pint != &global);
     destroy(s);
     assert(s.pint != &global); // fails
}
```
https://run.dlang.io/is/SFbxNm

How about:
"Destroys the given object `obj` and puts `obj` in its `T.init` 
state. This function used to destroy an object such that any 
cleanup by the destructor or finalizer is done, and such that 
`obj` no longer references any other objects (unless `T.init` 
references other objects). This function does not initiate a GC 
cycle nor free any GC memory."

regards,
   Johan