That being said, I usually work in Scala which provides language-based tools for that, so it definitely helps with avoiding the "dark magic" sentiment you may have had.
But why was it done that way ? It reduces boilerplate, copy-paste errors, code duplication, in ways sometimes not made possible by inheritance or composition.
// This %thing% was generated from %template% using data from %data%.
If your language is too restrictive to add sensible tools, you should write the tools yourself. As with any code, write it in a way such that other people will be able to understand it.
There is no magic, it's just code. I wish people would stop using that word.
Where would you and the comment in a situation like that one?
I don't have anything against generated code but it should be visible and, as you said, it should be crystal clear where it come from
If the class is being used, then the definition has got to be somewhere, hopefully in a header. It's simply a file that is included somewhere. And it will be human readable. There is no magic.
Sometimes you have to get the job done in a "less than ideal" way. But a lot of documentation/comments should be left to justify and more importantly explain how it works.
If that sounds unlikely to you, it sounded unlikely to me, too. I wasted a lot of time trying to figure out where they were defined. I couldn't ask the original author of the code; he had moved on.
Eventually, I found them, sort of. They were being defined by a sed script that ran during the build process. It read the sources before they got to the compiler, constructed class definitions on the fly, and injected them into the code before it was fed to the compiler. So the definitions were right there in the code that the compiler saw; they just weren't anywhere in the code that humans could see.
Why was it done that way? I have no idea.