From 6a824e90c12f003bae4ef47d5ee7de441c1d5de3 Mon Sep 17 00:00:00 2001
From: Jieyou Xu <jieyouxu@outlook.com>
Date: Tue, 8 Apr 2025 15:07:48 +0800
Subject: [PATCH] compiletest: document
 `{ignore,only}-{$target_triple,$target_arch}` impl limitation

---
 src/tests/directives.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/src/tests/directives.md b/src/tests/directives.md
index 8e4a71017..41d603706 100644
--- a/src/tests/directives.md
+++ b/src/tests/directives.md
@@ -129,6 +129,19 @@ means the test won't be compiled or run.
 
 Some examples of `X` in `ignore-X` or `only-X`:
 
+> NOTE:
+>
+> There's a current compiletest implementation limitation that an allow list is used
+> to help check for unknown directives (`src/tools/compiletest/src/directive-list.rs`).
+> The target triples and target archs for `//@ {ignore,only}-$target_triple` and
+> `//@ {ignore,only}-$target_arch` are computed based on all the builtin target specs,
+> such that they may be functional directives but are not listed in the known directives
+> allow list. In that case, you can `//@ {ignore,only}-{$target_triple,$target_arch}` to
+> the directives allow list.
+>
+> We would like to rework directive handling to make this allow list unnecessary in the
+> future.
+
 - A full target triple: `aarch64-apple-ios`
 - Architecture: `aarch64`, `arm`, `mips`, `wasm32`, `x86_64`, `x86`,
   ...