[LangRef] Try to clarify some Metadata semantics (#81948)

General cleanup in LangRef (and two outdated comments in LLParser.cpp)
with the aim of making it easier to understand some of the terminology
and subtle idiosyncrasies related to metadata in the IR.

I'm still not happy with the fact that "node" is used both informally
and with a particular category of metadata in mind, depending on the
context. This also bleeds into the type names in the implementation.

There are also several places where names from the implementation appear
in the document with no other context or definition. In some cases I
added a parenthetical to section titles to tie the two together, but I
don't think this is ideal.

I also think it might be useful to define the "abstract" metadata
classes like "DIScope" in the document, so the hierarchy of metadata
node kinds is direct, and so we can avoid repetitive descriptions of all
of the members of on part of the hierarchy. This inheritance doesn't
have to be in terms of C++ classes, but using the same names as the
implementation seems helpful, and we already do it for many other
things.

Finally I added sections for the specialized nodes which are implemented
in the IR but didn't have documentation in LangRef yet. These could use
some work, and I admit I didn't dig too deep into the specifics beyond
enumerating the fields, but I think we would ideally always have a
LangRef section for every kind of node.

0 files changed, 0 insertions, 0 deletions