Merge pull request GaijinEntertainment#2106 from GaijinEntertainment/doc-doc-2

pass macro documentation

Author: borisbat

doc/source/reference/language/macros.rst

@@ -446,22 +446,32 @@ Note how the name is provided in the ``[call_macro]`` annotation.
 AstPassMacro
 ------------
 
-``AstPassMacro`` is one macro to rule them all. It gets entire module as an input,
-and can be invoked at numerous passes:
+``AstPassMacro`` is one macro to rule them all. It gets the entire program as
+input and can be invoked at numerous passes:
 
 .. code-block:: das
 
     class AstPassMacro {
-        def abstract apply ( prog:ProgramPtr; mod:Module? ) : bool
+        def abstract apply(prog : ProgramPtr; mod : Module?) : bool
     }
 
+Five annotations control when a pass macro runs:
+
+- ``[infer_macro]`` — after clean type inference.  Returning ``true`` re-infers.
+- ``[dirty_infer_macro]`` — during each dirty inference pass.
+- ``[lint_macro]`` — after successful compilation (lint phase, read-only).
+- ``[global_lint_macro]`` — same as ``[lint_macro]`` but for all modules.
+- ``[optimization_macro]`` — during the optimisation loop.
+
 ``make_pass_macro`` registers a class as a pass macro.
 
-``add_new_infer_macro`` adds a pass macro to the infer pass. The ``[infer]`` annotation accomplishes the same thing.
+Typically, such macros create an ``AstVisitor`` which performs the necessary
+transformations via ``visit(prog, adapter)``.
 
-``add_new_dirty_infer_macro`` adds a pass macro to the ``dirty`` section of infer pass. The ``[dirty_infer]`` annotation accomplishes the same thing.
+.. seealso::
 
-Typically, such macros create an ``AstVisitor`` which performs the necessary transformations.
+   :ref:`tutorial_macro_pass_macro` — step-by-step tutorial with lint and
+   infer macro examples.
 
 ----------------
 AstTypeInfoMacro

doc/source/reference/tutorials.rst

@@ -157,4 +157,5 @@ Run any tutorial from the project root::
    tutorials/macros/10_capture_macro.rst
    tutorials/macros/11_reader_macro.rst
    tutorials/macros/12_typeinfo_macro.rst
-   tutorials/macros/13_enumeration_macro.rst
+   tutorials/macros/13_enumeration_macro.rst
+   tutorials/macros/14_pass_macro.rst

doc/source/reference/tutorials/macros/13_enumeration_macro.rst

@@ -297,6 +297,8 @@ enumeration macro use cases:
 
    Previous tutorial: :ref:`tutorial_macro_typeinfo_macro`
 
+   Next tutorial: :ref:`tutorial_macro_pass_macro`
+
    Standard library: ``daslib/enum_trait.das`` —
    :ref:`enum_trait module reference <stdlib_enum_trait>`