docs: Fix many build_target based issueswip/xclaesse/pr-10714

This is still not fully correct, but it's much better. There are two
problems that are somewhat difficult to solve:

 1) although they are polymorphic from an attributes/methods standpoint,
    `static_library()`, `shared_library()`, and `shared_module()`
    actually return distinct types, and they are not always valid in the
    same places; ie, only StaticLibrary can be passed to `link_whole:`
 2) several arguments that are common to all take different types,
    namely `sources`
 3) `jar()` is really it's own thing, and should be treated as its own
    thing, not sharing the same base class. That means replicating for
    build_targets() the same sort of structure that exists in
    type_checking.py

4 files changed, 56 insertions, 6 deletions

diff --git a/docs/yaml/functions/_build_target_base.yaml b/docs/yaml/functions/_build_target_base.yaml
index 767c4da6a..5998e788d 100644
--- a/docs/yaml/functions/_build_target_base.yaml
+++ b/docs/yaml/functions/_build_target_base.yaml
@@ -49,9 +49,14 @@ kwargs:
       eg: `cpp_args` for C++
 
   sources:
-    type: str | file | custom_tgt | custom_idx | generated_list | structured_src
+    type: list[str | file | custom_tgt | custom_idx | generated_list | structured_src]
     description: Additional source files. Same as the source varargs.
 
+  resources:
+    type: list[str]
+    description: |
+      Resources files for .net applications (currently limited to C#)
+
   build_by_default:
     type: bool
     default: true
@@ -78,7 +83,7 @@ kwargs:
       (for deps built by the project)
 
   extra_files:
-    type: str | file | custom_tgt | custom_idx
+    type: list[str | file]
     description: |
       Not used for the build itself but are shown as source files in IDEs
       that group files by targets (such as Visual Studio)
@@ -132,6 +137,9 @@ kwargs:
       custom targets. The user must ensure that the output is a library in
       the correct format.
 
+      All targets must be *statically* linkable. Therefore, only "staticlib",
+      "bothlib", and "custom targets" that produce static archives may be passed.
+
   link_with:
     type: list[lib | custom_tgt | custom_idx]
     description: |
@@ -191,7 +199,7 @@ kwargs:
       (but *not* before that). On Windows, this argument has no effect.
 
   objects:
-    type: list[extracted_obj | file | str]
+    type: list[extracted_obj | file | str | custom_tgt | custom_idx | generated_list]
     description: |
       List of object files that should be linked in this target.
 
@@ -248,7 +256,7 @@ kwargs:
       do not support GNU visibility arguments.
 
   d_import_dirs:
-    type: list[str]
+    type: list[str | inc]
     description: List of directories to look in for string imports used in the D programming language.
 
   d_unittest:
@@ -261,7 +269,7 @@ kwargs:
     description: List of module version identifiers set when compiling D sources.
 
   d_debug:
-    type: list[str]
+    type: list[str | int]
     description: |
       The [D version identifiers](https://dlang.org/spec/version.html#version) to add
       during the compilation of D source files.
@@ -302,3 +310,22 @@ kwargs:
       "proc-macro" is a special rust proceedural macro crate.
 
       "proc-macro" is new in 0.62.0.
+
+  vala_header:
+    type: str
+    description: |
+      The name of a vala import header to generate. If left undefined the base
+      name of the target will be used. Is not generated for [[executable]]s that
+      do not also set export_dynamic.
+
+  vala_vapi:
+    type: str
+    description: |
+      The name of a vala vapi file generate. If left undefined the base
+      name of the target will be used. Is not generated for [[executable]]s that
+      do not also set export_dynamic.
+
+  vala_gir:
+    type: str
+    description: |
+      The name of a gir file to generate. If undefined no gir file will be generated.
diff --git a/docs/yaml/functions/executable.yaml b/docs/yaml/functions/executable.yaml
index cdf764a07..3434d23f0 100644
--- a/docs/yaml/functions/executable.yaml
+++ b/docs/yaml/functions/executable.yaml
@@ -20,6 +20,7 @@ kwargs_inherit: _build_target_base
 kwargs:
   export_dynamic:
     type: bool
+    default: false
     since: 0.45.0
     description: |
        when set to true causes the target's symbols to be
@@ -44,3 +45,24 @@ kwargs:
     type: bool
     since: 0.49.0
     description: Build a position-independent executable.
+
+  gui_app:
+    type: bool
+    default: false
+    deprecated: 0.56
+    description: |
+      If set to true this executable will be compiled as a Windows GUI subsystem
+      application. Hs no effect on non-windows platforms.
+
+      Use `win_subsystem` instead
+
+  win_subsystem:
+    type: str
+    default: console
+    since: 0.56
+    description: |
+      Pick which windows subsystem this executable should be built format.
+
+      This replaces `gui_app`, and setting it to `console` is equivalent to
+      `gui_app : false`, setting it to `windows` is equivalent to `gui_app :
+      true`.
diff --git a/docs/yaml/functions/shared_library.yaml b/docs/yaml/functions/shared_library.yaml
index 956fb2cb2..38bab848d 100644
--- a/docs/yaml/functions/shared_library.yaml
+++ b/docs/yaml/functions/shared_library.yaml
@@ -29,7 +29,7 @@ kwargs:
       `soversion` is not defined, it is set to `3`.
 
   darwin_versions:
-    type: str | int | list[str]
+    type: str | int | list[str | int]
     since: 0.48.0
     description: |
       Defines the `compatibility version` and `current version` for the dylib on macOS.
diff --git a/docs/yaml/functions/static_library.yaml b/docs/yaml/functions/static_library.yaml
index 1d42d600a..b156949f4 100644
--- a/docs/yaml/functions/static_library.yaml
+++ b/docs/yaml/functions/static_library.yaml
@@ -18,6 +18,7 @@ kwargs:
 
   prelink:
     type: bool
+    default: false
     since: 0.57.0
     description: |
       If `true` the object files in the target will be prelinked,