Debug Information Interface / Documentation

Hi all,

We had some problems in the past when generating debug information,
for which I have started a documentation [1]. The recent change to
DIBuilder made it more difficult to check for inconsistencies, since
neither the original interface nor the current one are documented.

This is creating a lot of problems when integrating our front-end to
LLVM and we never quite got the debug information working. From
generating wrong information to just plain bad Dwarf (and crashing
Dwarf consumers), it's so unreliable that we just can't use it for
anything. I recently sent an example where a vanilla Clang/LLVM
generates a completely wrong information on ARM. Other front-end
developers are reporting the same issues.

My concerns are:
- The interface documentation [2] is outdated and not detailed enough
(as is [3]), so it's hard to know what to generate;
- The API is undocumented and it changed recently (also changing the
interface slightly), which makes it *very* hard to keep-up;
- The end result was (and still is) producing wrong and/or bad Dwarf;
- The only documentation we have is the code, which is in constant
change and has a lot of context;

Can we work out a proper stable interface and, if possible, a
reasonably stable API?

I'm volunteering (again) to start, but I need help, otherwise it'll be
yet another [1].