[all-commits] [llvm/llvm-project] eee8c6: [LangRef] Try to clarify some Metadata semantics (...

[Scott Linder via All-commits]

  Branch: refs/heads/main
  Home:   https://github.com/llvm/llvm-project
  Commit: eee8c6150a1c3af54542d34d1c084a86feda4d96
      https://github.com/llvm/llvm-project/commit/eee8c6150a1c3af54542d34d1c084a86feda4d96
  Author: Scott Linder <72270781+slinder1 at users.noreply.github.com>
  Date:   2024-03-28 (Thu, 28 Mar 2024)

  Changed paths:
    M llvm/docs/LangRef.rst
    M llvm/lib/AsmParser/LLParser.cpp

  Log Message:
  -----------
  [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.



To unsubscribe from these emails, change your notification settings at https://github.com/llvm/llvm-project/settings/notifications