[clang] [clang][doc] Add documentation for the ASTs used to represent C++ templates (PR #66436)

[Scott McPeak via cfe-commits]

smcpeak wrote:

Hi Tom!  :)

Indeed, any documentation brings with it an ongoing maintenance burden.

There are two main things I see that need synchronization: the text descriptions of the fields, and the diagrams.

For the fields, one idea I had is to write a script that runs as part of the tests and would scrape the declarations (and maybe the Doxygen comments too) from the C++ source and then compare them to previously scraped fragments embedded as comments in `ASTsForTemplates.rst`.  The idea is if a declaration that is documented changes, the script would alert the one making the change that the corresponding documentation might need to be adjusted.  After adjusting as needed, the scraped fragment in the document would be updated (by the same person), thereby returning to the "in sync" state.

For the diagrams, they are generated in a semi-automatic way: a tool (`print-clang-ast`) generates a graph of AST nodes, then the diagram selectively imports nodes, attributes, and pointers from that graph.  If the tool were in the Clang repo, it would be straightforward to, for each diagram, have it regenerate the graph and compare to the graph stored in the diagram file.  This comparison can be done without using the `ded` program because the entire diagram, including the embedded graph, is in a JSON format.  If the graphs are found to differ, it means the diagram needs to be updated; that *would* required `ded`, which has features to reimport an updated graph, perform localized repairs, and check consistency between the diagram and graph.

I'd be willing to do both of the above if people think either or both is a good approach.

As for the utility of the diagrams, I think they are the most important part of the document since they allow the reader to see how all of the elements work together, solidifying the material in the text that precedes them.  Studying the diagrams was the primary way I learned this material in the first place.


https://github.com/llvm/llvm-project/pull/66436