[clang] [llvm] [clang] Add/enhance documentation for some important classes. (PR #109795)

[kadir çetinkaya via llvm-commits]

================
@@ -79,8 +79,24 @@ enum class StringLiteralKind;
 // AST classes for statements.
 //===----------------------------------------------------------------------===//
 
-/// Stmt - This represents one statement.
+/// A statement or expression in the program.
 ///
+/// This is the base for the hierarchy of statements (ForStmt, ReturnStmt...)
+/// as well as expressions (Expr, CastExpr, IntegerLiteral...).
+/// Classing expressions as Stmt allows them to appear as statements without
+/// needing an extra "expression-statement" node.
+///
+/// Statements can have children and so form trees. e.g. `while (i>0) i--;`:
+///
+///     WhileStmt
+///     |-BinaryOperator >
+///     | |-DeclRefExpr i
+///     | `-IntegerLiteral 0
+///     `-UnaryOperator --
+///       `-DeclRefExpr i
+///
+/// These trees are often rooted at function bodies, and attach to the rest
+/// of the AST via FunctionDecls.
----------------
kadircet wrote:

i am not sure what's the value we get out of this paragraph. maybe just emphasize they usually attach the AST via Decls?

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