Thanks for sharing that.
I will see with our documentation team if this can be documented.
We try to shape our documentation with a minimal amount of technicalities. The purpose is and should be functional. For more advanced and rare questions, we are thinking of a way to shape it. It is currently spread across the community forum. We will announce if something more usable comes out of it.
It is probably already on the community forum; I can restate it here. The build-wrapper intercepts the entire processes tree spawned by the passed build command. It works by shared library injection. As a result, it does not work with statically linked tools (especially some compilers). The build-wrapper can recognize supported compiler calls and output this information among all the intercepted command lines. The analyzer then uses it to parse your C and C++ code exactly as your compiler does.
I am not sure I understand your question very precisely. The only way I can think of to attach metadata to an analysis is indeed through code variant. If you have something more specific in mind with use cases, you are very welcome to open a new thread about it. We will be glad to discuss it.
Thanks for reiterating this on the list for completeness. I hope my previous answer was clear.