[C++] Document usage of C++ types, limitations, and patterns

[Geod24]

Currently we don't have a good documentation about what can, should, and shouldn't be done with extern(C++) types. Given there are a lot of technicalities involved, it would be good to have a rather extensive documentation.

Such a documentation would introduce knowledge of constructs in D that are safe to use, as well as C++-specific knowledge, for example copy constructors, default constructors, constructors deletion, move constructors, non-representable types, etc...

That documentation is also very likely to be specific to the version of C++ we're using (there are some subtle differences between C++11, C++14 and C++17, and we're currently using the later).

Another note: The D documentation for C++ interfacing is wildly outdated...

[AndrejMitrovic]

Hmm yeah. Looking at it now again, we return vectors to the C++ side - for example in combineCandidates. But when we return it by value we don't do a deep copy (to the C heap), the vectors still contain references to GC allocated memory (which then goes out of scope).

[Geod24]

Return by value is actually fine, it uses NRVO so dtor / copy ctors are not involved

[Geod24]

Re unwanted moves, on the C++ side we have https://reviews.llvm.org/D43322 (flag -Wreturn-std-move).