Improve description of how =trace is used (#18491)

* [skip ci] thamming_orc test created/destroyed counts match

The thamming_orc.nim code now counts all created objects being tested, not just the ones following the "first 20" test, and the position of the `destroyed += 1` counter has been adjusted so it counts all the calls that are as a result of `=trace` tracing and not just the original destruction calls.

* Improve description of how `=trace` is used

The following nuances weren't previously fully explained:

1. That `=trace` is only used by `--gc:orc`.
2. That `=trace` is almost certainly used along with `=destroy` when manual resource allocation has been used, but it is only required if there is a possibility of cyclic references in the wrapped types (ie. generic types).
3. That, currently, a forward definition is required for the second of the pair to avoid an auto compiler generation conflict.

The pattern of the use of `=trace` has also been made more extensive, showing how both a custom `=destroy` and `=trace` are used for manual allocation of resources when there is any possibility of a cyclic reference in the resource-wrapped values.

* Update doc/destructors.rst

Co-authored-by: Andreas Rumpf <rumpf_a@web.de>

0 files changed, 0 insertions, 0 deletions