docs: Update YAML docs after rebase

4 files changed, 59 insertions, 13 deletions

diff --git a/docs/yaml/elementary/str.yml b/docs/yaml/elementary/str.yml
index e55243f..b79577a 100644
--- a/docs/yaml/elementary/str.yml
+++ b/docs/yaml/elementary/str.yml
@@ -219,10 +219,15 @@ methods:
     # path now has the value '/usr/bin:/bin:/usr/local/bin'
     ```
 
-  posargs:
-    string_list:
-      type: list[str]
-      description: The list to join with the current string
+  varargs:
+      name: strings
+      type: str
+      since: 0.60.0
+      description: |
+        The strings to join with the current string.
+
+        Before Meson *0.60.0* this function only accepts a single positional
+        argument of the type [[list[str]]].
 
 # str.underscorify
 - name: underscorify
diff --git a/docs/yaml/functions/custom_target.yaml b/docs/yaml/functions/custom_target.yaml
index 93e901a..bfc7da9 100644
--- a/docs/yaml/functions/custom_target.yaml
+++ b/docs/yaml/functions/custom_target.yaml
@@ -2,8 +2,18 @@ name: custom_target
 returns: custom_tgt
 description: |
   Create a custom top level build target. The only positional argument
-  is the name of this target and the keyword arguments are the
-  following.
+  is the name of this target and cannot contain path separators (`/` or `\`).
+  The name of custom target might not be used by every backends, for instance with
+  the Ninja backend, `subdir/meson.build` containing the example below,
+  `ninja -C builddir foo` or `ninja -C builddir subdir/foo` won't work,
+  it is instead `ninja -C builddir subdir/file.txt`. Howerver, `meson compile subdir/foo`
+  is accepted.
+  ```meson
+  custom_target('foo', output: 'file.txt', ...)
+  ```
+
+  *Since 0.60.0* the name argument is optional and defaults to the basename of the first
+  output (`file.txt` in the example above).
 
   The list of strings passed to the `command` keyword argument accept
   the following special string substitutions:
@@ -42,10 +52,14 @@ notes:
     is not portable, notably to Windows. Instead, consider using a
     `native: true` [[executable]], or a python script.
 
-posargs:
+optargs:
   name:
     type: str
-    description: The *unique* id of the custom target
+    description: |
+      The *unique* id of the custom target
+
+      This posarg is optional *since 0.60.0*. It defaults to the basename
+      of the first output.
 
 kwargs:
   build_by_default:
@@ -138,6 +152,9 @@ kwargs:
       compiler would list all the header files it included, and a change
       in any one of these files triggers a recompilation.
 
+      *(since 0.47.0)* the `@BASENAME@` and `@PLAINNAME@` substitutions
+      are also accepted.
+
   input:
     type: list[str | file]
     description: List of source files. *(since 0.41.0)* the list is flattened.
diff --git a/docs/yaml/functions/dependency.yaml b/docs/yaml/functions/dependency.yaml
index 1a01bbc..dcb696d 100644
--- a/docs/yaml/functions/dependency.yaml
+++ b/docs/yaml/functions/dependency.yaml
@@ -8,6 +8,13 @@ description: |
   logic](Dependencies.md#dependencies-with-custom-lookup-functionality)
   are also supported.
 
+  *Since 0.60.0* more than one name can be provided, they will be tried in order
+  and the first name to be found will be used. The fallback subproject will be
+  used only if none of the names are found on the system. Once one of the name has
+  been found, all other names are added into the cache so subsequent calls for any
+  of those name will return the same value. This is useful in case a dependency
+  could have different names, such as `png` and `libpng`.
+
   Dependencies can also be resolved in two other ways:
 
   * if the same name was used in a `meson.override_dependency` prior to
@@ -48,10 +55,21 @@ notes:
     dependencies such as Qt5 or Boost. `components` allows the user to manually
     add CMake `COMPONENTS` for the `find_package` lookup)
 
-posargs:
-  dependency_name:
-    type: str
-    description: Name of the dependency too look up
+varargs:
+  name: names
+  type: str
+  since: 0.60.0
+  min_varargs: 1
+  description: |
+    The names of the dependency too look up. The dependencies are looked up in
+    the order they are provided here. The first found dependency will then be
+    used. The fallback subproject will be used only if none of the names are
+    found on the system. Once one of the name has been found, all other names
+    are added into the cache so subsequent calls for any of those name will
+    return the same value. This is useful in case a dependency could have
+    different names, such as `png` and `libpng`.
+
+    **NOTE:** Before *0.60.0* only a single dependency name was allowed.
 
 kwargs:
   default_options:
diff --git a/docs/yaml/objects/compiler.yaml b/docs/yaml/objects/compiler.yaml
index d4f0715..78e8ce1 100644
--- a/docs/yaml/objects/compiler.yaml
+++ b/docs/yaml/objects/compiler.yaml
@@ -297,7 +297,13 @@ methods:
 
 - name: links
   returns: bool
-  description: Returns true if the code compiles and links.
+  description: |
+    Returns true if the code compiles and links.
+
+    *Since 0.60.0*, if the `file` object's
+    suffix does not match the compiler object's language, the compiler
+    corresponding to the suffix is used to compile the source, while the
+    target of the `links` method is used to link the resulting object file.
   posargs_inherit: compiler._code
   kwargs_inherit: compiler._compiles