fix: Document and fix IWYU (#2765)

adding some documentation and fix the params

.github/workflows/iwyu.yml

@@ -55,7 +55,7 @@ jobs:
           -DACTS_BUILD_EXAMPLES_EDM4HEP=ON
 
       - name: Run IWYU
-        run: python3 iwyu-install/bin/iwyu_tool.py -p acts-build/ -j2 -- --mapping_file=acts/CI/iwyu/mapping.imp | tee iwyu-output.txt
+        run: python3 iwyu-install/bin/iwyu_tool.py -p acts-build/ -j2 -- -Xiwyu --mapping_file=acts/CI/iwyu/mapping.imp | tee iwyu-output.txt
       - name: Filter IWYU output
         run: python3 acts/CI/iwyu/filter.py acts/CI/iwyu/filter.yaml iwyu-output.txt iwyu-filtered.txt
       - name: Apply IWYU

CI/iwyu/README.md

@@ -0,0 +1,16 @@
+# IWYU = Include what you use
+
+This tool finds unused includes and suggestes additional includes and declarations.
+
+It is not very stable at the moment and takes a few hours to complete within ACTS therefor it only runs once a week and can be triggered manually.
+
+There is also not sufficient filtering offered by IWYU at the moment. For that reason there is a specific filtering script for now which tries to get rid of unwanted changes.
+
+offline resources
+- [GitHub Actions Workflow](../../.github/workflows/iwyu.yml)
+- [Custom filter script](./filter.py)
+
+online resources
+
+- https://include-what-you-use.org/
+- https://github.com/include-what-you-use/include-what-you-use

CI/iwyu/filter.yaml

@@ -1,5 +1,5 @@
 remove_lines:
-  # ignore unexiting std
+  # ignore if not existing in std
   - "^#include <new>"
   - "^#include <bits/"
   - "^#include <ext/"
@@ -8,7 +8,7 @@ remove_lines:
   - "namespace Eigen {"
   # ignore boost
   - "^(- )?#include <boost/"
-  # don remove ipp
+  # don't remove ipp
   - "^- #include [<\"].*\\.ipp"
   # ignore pybind11
   - "^(- )?#include <pybind11/"
@@ -21,7 +21,7 @@ replace_lines:
   - "^#include <unistd\\.h>": "#include <cunistd>"
   - "^#include <stdint\\.h>": "#include <cstdint>"
   - "^#include <stdlib.h>": "#include <cstdlib>"
-  # don use ipp
+  # don't use ipp
   - "^#include ([<\"].*)\\.ipp": "#include \\1.hpp"
 
 ignore_files: