ast_passes/validation: update module docs

- Syntax extensions are replaced by proc macros.
- Add rationale for why AST validation pass need to be run
  post-expansion and why the pass is needed in the first place.

compiler/rustc_ast_passes/src/ast_validation.rs

@@ -1,10 +1,13 @@
-// Validate AST before lowering it to HIR.
+//! Validate AST before lowering it to HIR.
-//
+//!
-// This pass is supposed to catch things that fit into AST data structures,
+//! This pass intends to check that the constructed AST is *syntactically valid* to allow the rest
-// but not permitted by the language. It runs after expansion when AST is frozen,
+//! of the compiler to assume that the AST is valid. These checks cannot be performed during parsing
-// so it can check for erroneous constructions produced by syntax extensions.
+//! because attribute macros are allowed to accept certain pieces of invalid syntax such as `async
-// This pass is supposed to perform only simple checks not requiring name resolution
+//! fn` within a trait (before async-fn-in-trait was introduced).
-// or type checking or some other kind of complex analysis.
+//!
+//! These checks are run post-expansion, after AST is frozen, to be able to check for erroneous
+//! constructions produced by proc macros. This pass is only intended for simple checks that do not
+//! require name resolution or type checking, or other kinds of complex analysis.
 
 use itertools::{Either, Itertools};
 use rustc_ast::ptr::P;