[spec/struct] Improve struct destructor docs (#3638)

Mention dtor called before assignment.
Add example.
Add link to RAII.
Add heading for union field destruction.

Mention struct dtor in RAII glossary and link to scope class variables.

Author: ntrel

spec/glossary.dd

@@ -213,13 +213,15 @@ void test()
         the $(LINK2 $(ROOT_DIR)spec/const3.html, language rules).)
 
         $(DT $(LNAME2 raii, $(ACRONYM RAII, Resource Acquisition Is Initialization)))
-        $(DD RAII refers to the technique of having the destructor
-        of a class object called when the object goes out of scope.
+        $(DD RAII refers to the technique of having the
+        $(DDSUBLINK spec/struct, struct-destructor, destructor
+        of a struct) or class object called when the object goes out of scope.
         The destructor then releases any resources acquired by
         that object.
         RAII is commonly used for resources that are in short supply
         or that must have a predictable point when they are released.
-        RAII objects in D are created using the $(D scope) storage class.
+        RAII can be used for class variables declared with the
+        $(DDSUBLINK spec/attribute, scope-class-var, $(D scope) storage class).
         )
 
         $(DT $(LNAME2 rvalue, rvalue))

spec/struct.dd

@@ -1770,13 +1770,47 @@ void main()
 
 $(H2 $(LEGACY_LNAME2 StructDestructor, struct-destructor, Struct Destructors))
 
-        $(P Destructors are called when an object goes out of scope.
+        $(P Destructors are called when an object goes out of scope, or
+        $(RELATIVE_LINK2 assign-overload, before an assignment).
         Their purpose is to free up resources owned by the struct
         object.
         )
 
+$(SPEC_RUNNABLE_EXAMPLE_RUN
+---
+struct S
+{
+    int i;
+
+    ~this()
+    {
+        import std.stdio;
+        writeln("S(", i, ") is being destructed");
+    }
+}
+
+void main()
+{
+    auto s1 = S(1);
+    {
+        auto s2 = S(2);
+        // s2 destructor called
+    }
+    S(3); // s3 destructor called
+    // s1 destructor called
+}
+---
+)
+        $(P The destructor can also be called early using $(REF1 destroy, object)
+        or by assigning the struct's `init` property.)
+
+        $(P Struct destructors are used for $(DDSUBLINK spec/glossary, raii, RAII).)
+
+
+$(H2 $(LNAME2 union-field-destruction, Union Field Destruction))
+
         $(P Unions may have fields that have destructors. However, a union itself never has
-        a destructor. When a union goes out of scope, destructors for its fields are not called.
+        a destructor. When a union goes out of scope, destructors for its fields *are not called*.
         If those calls are desired, they must be inserted explicitly by the programmer:)
 
 $(SPEC_RUNNABLE_EXAMPLE_COMPILE