document and raise an error for disallowed combination of install_headers args

It makes no sense to specify both:
- install_dir, which overrides the -Dincludedir= builtin option
- subdir, which suffixes the -Dincludedir= builtin option

We've always silently ignored the subdir in this case, which is really
surprising if someone actually passed it and expected it to do
something. We also confusingly didn't say anything in the documentation
about it.

Document that the options are incompatible, and explicitly check to see
if they are both passed -- if so, raise an error message pointing out
that only install_dir should be used.

Fixes #10046

1 files changed, 5 insertions, 2 deletions

diff --git a/docs/yaml/functions/install_headers.yaml b/docs/yaml/functions/install_headers.yaml
index 8dc8205..cf8fb9f 100644
--- a/docs/yaml/functions/install_headers.yaml
+++ b/docs/yaml/functions/install_headers.yaml
@@ -37,11 +37,14 @@ varargs:
 kwargs:
   install_dir:
     type: str
-    description: Where to install to
+    description: Where to install to.
 
   subdir:
     type: str
-    description: Use the `subdir` in the `install_dir`
+    description: |
+      Install to the `subdir` subdirectory of the default includedir.
+
+      Incompatible with the `install_dir` kwarg.
 
   install_mode:
     type: list[str | int]