docs: Add the YAML Reference manual

26 files changed, 1300 insertions, 0 deletions

diff --git a/docs/yaml/objects/alias_tgt.yaml b/docs/yaml/objects/alias_tgt.yaml
new file mode 100644
index 0000000..bd36502
--- /dev/null
+++ b/docs/yaml/objects/alias_tgt.yaml
@@ -0,0 +1,4 @@
+name: alias_tgt
+long_name: Alias target
+description: Opaque object returned by [[alias_target]].
+extends: tgt
diff --git a/docs/yaml/objects/both_libs.yaml b/docs/yaml/objects/both_libs.yaml
new file mode 100644
index 0000000..36e5baa
--- /dev/null
+++ b/docs/yaml/objects/both_libs.yaml
@@ -0,0 +1,14 @@
+name: both_libs
+long_name: Both libraries object
+extends: lib
+description: Container for both a static and shared library.
+since: 0.46.0
+
+methods:
+  - name: get_shared_lib
+    returns: lib
+    description: Returns the stored shared library
+
+  - name: get_static_lib
+    returns: lib
+    description: Returns the stored static library
diff --git a/docs/yaml/objects/build_tgt.yaml b/docs/yaml/objects/build_tgt.yaml
new file mode 100644
index 0000000..e1c8a80
--- /dev/null
+++ b/docs/yaml/objects/build_tgt.yaml
@@ -0,0 +1,41 @@
+name: build_tgt
+long_name: Build target
+extends: tgt
+description: |
+  A build target is either an executable, shared library, static library,
+  both shared and static library or shared module.
+
+  TODO: Missing methods, links
+
+methods:
+- name: full_path
+  returns: str
+  description: |
+    Returns a full path pointing to the result target file.
+    **NOTE:** In most cases using the object itself will do the same job
+    as this and will also allow Meson to setup inter-target dependencies
+    correctly. Please file a bug if that doesn't work for you.
+
+- name: path
+  returns: str
+  since: 0.59.0
+  deprecated: 0.59.0
+  description: |
+    Does the exact same as [[build_tgt.full_path]]. **NOTE**: This
+    function is solely kept for compatebility with [[@external_program]] objects.
+    It will be removed once the, also deprecated, corresponding `path()`
+    function in the [[@external_program]] object is removed.
+
+- name: name
+  returns: str
+  since: 0.54.0
+  description: Returns the name of the target.
+
+- name: found
+  returns: bool
+  since: 0.59.0
+  description: |
+    Always returns `true`. This function is meant to make executables
+    objects feature compatible with [[@external_program]] objects. This
+    simplifies use-cases where an executable is used instead of
+    an [[@external_program]].
diff --git a/docs/yaml/objects/cfg_data.yaml b/docs/yaml/objects/cfg_data.yaml
new file mode 100644
index 0000000..9a66b73
--- /dev/null
+++ b/docs/yaml/objects/cfg_data.yaml
@@ -0,0 +1,128 @@
+name: cfg_data
+long_name: Configuration data object
+description: |
+  This object encapsulates
+  configuration values to be used for generating configuration files. A
+  more in-depth description can be found in the [the configuration wiki
+  page](Configuration.md).
+
+methods:
+- name: set
+  returns: void
+  description: Sets a variable to a given value
+
+  posargs:
+    varname:
+      type: str
+      description: The name of the variable to set
+    value:
+      type: str | int | bool
+      description: The value to set
+
+  kwargs:
+    description:
+      type: str
+      description: |
+        Message / Comment that will be written in the
+        result file. The replacement assumes a file with C syntax. If your
+        generated file is source code in some other language, you probably
+        don't want to add a description field because it most likely will
+        cause a syntax error.
+
+- name: set10
+  returns: void
+  description: |
+    Is the same as [[cfg_data.set]] but the value
+    is either `true` or `false` and will be written as 1 or 0,
+    respectively
+
+  posargs:
+    varname:
+      type: str
+      description: The name of the variable to set
+    value:
+      type: bool
+      description: The value to set as either `1` or `0`
+
+  kwargs_inherit: cfg_data.set
+
+- name: set_quoted
+  returns: void
+  description: Is same as [[cfg_data.set]] but quotes the value in double quotes (`"`)
+
+  posargs:
+    varname:
+      type: str
+      description: The name of the variable to set
+    value:
+      type: str | int | bool
+      description: The value to set
+
+  kwargs_inherit: cfg_data.set
+
+- name: get
+  returns: str | int | bool
+  since: 0.38.0
+  description: |
+    Returns the value of `varname`, if the
+    value has not been set returns `default_value` if it is defined
+    *(since 0.38.0)* and errors out if not
+
+  posargs:
+    varname:
+      type: str
+      description: The name of the variable to query
+
+  optargs:
+    default_value:
+      type: str | int | bool
+      description: The default value to return when `varname` does not exist
+
+- name: get_unquoted
+  returns: str | int | bool
+  since: 0.44.0
+  description: |
+    Returns the value
+    of `varname` but without surrounding double quotes (`"`). If the value has
+    not been set returns `default_value` if it is defined and errors out if not.
+
+  posargs:
+    varname:
+      type: str
+      description: The name of the variable to query
+
+  optargs:
+    default_value:
+      type: str | int | bool
+      description: The default value to return when `varname` does not exist
+
+- name: has
+  returns: bool
+  description: returns `true` if the specified variable is set
+  posargs:
+    varname:
+      type: str
+      description: The name of the variable to query
+
+- name: keys
+  returns: list[str]
+  since: 0.57.0
+  description: |
+    Returns an array of keys of
+    the configuration data object.
+
+    You can iterate over this array with the [`foreach`
+    statement](Syntax.md#foreach-statements).
+
+- name: merge_from
+  returns: void
+  since: 0.42.0
+  description: |
+    Takes as argument a different
+    configuration data object and copies all entries from that object to
+    the current.
+
+  posargs:
+    other:
+      type: cfg_data
+      description: The other [[@cfg_data]] object to merge into this one.
diff --git a/docs/yaml/objects/compiler.yaml b/docs/yaml/objects/compiler.yaml
new file mode 100644
index 0000000..d4f0715
--- /dev/null
+++ b/docs/yaml/objects/compiler.yaml
@@ -0,0 +1,542 @@
+name: compiler
+long_name: Compiler object
+description: |
+  This object is returned by [[meson.get_compiler]].
+  It represents a compiler for a given language and allows you to query its properties.
+
+notes:
+- |
+  These compiler checks do not use compiler arguments added
+  with `add_*_arguments()`, via `-Dlang_args` on the command-line, or
+  through `CFLAGS`/`LDFLAGS`, etc in the environment. Hence, you can
+  trust that the tests will be fully self-contained, and won't fail
+  because of custom flags added by other parts of the build file or by
+  users.
+
+- |
+  Note that if you have a single prefix with all your dependencies, you
+  might find it easier to append to the environment variables
+  `C_INCLUDE_PATH` with GCC/Clang and `INCLUDE` with MSVC to expand the
+  default include path, and `LIBRARY_PATH` with GCC/Clang and `LIB` with
+  MSVC to expand the default library search path.
+
+  However, with GCC, these variables will be ignored when
+  cross-compiling. In that case you need to use a specs file. See:
+  http://www.mingw.org/wiki/SpecsFileHOWTO
+
+methods:
+
+# Helper methods to pre-define common posargs
+- name: _code
+  returns: void
+  description: You have found a bug if you can see this!
+  posargs:
+    code:
+      type: str | file
+      description: |
+        The source code to check.
+
+        If a string is passed, the code is used directly. If a [[@file]] object
+        is passed, it's content is used for the compiler check.
+
+# Helper methods to pre-define common kwargs
+- name: _args
+  returns: void
+  description: You have found a bug if you can see this!
+  kwargs:
+    args:
+      type: list[str]
+      description: |
+        Used to pass a list of compiler arguments.
+        Defining include paths for headers not in the default include path
+        via `-Isome/path/to/header` is generally supported, however, usually not
+        recommended.
+
+        This is because include directories can also be specified via the
+        `include_directories` or the `dependency` kwarg (if present).
+        The same is also true for passing libraries to link with `-lfoo`.
+
+- name: _include_directories
+  returns: void
+  description: You have found a bug if you can see this!
+  kwargs:
+    include_directories:
+      type: inc | list[inc]
+      since: 0.38.0
+      description: Extra directories for header searches.
+
+- name: _dependencies
+  returns: void
+  description: You have found a bug if you can see this!
+  kwargs:
+    dependencies:
+      type: dep | list[dep]
+      description: Additionally dependencies required for compiling and / or linking.
+
+- name: _prefix
+  returns: void
+  description: You have found a bug if you can see this!
+  kwargs:
+    prefix:
+      type: str
+      description: |
+        Used to add `#include`s and other things that are required
+        for the symbol to be declared. System definitions should be
+        passed via compiler args (eg: `_GNU_SOURCE` is often required for
+        some symbols to be exposed on Linux, and it should be passed via
+        `args` keyword argument).
+
+- name: _no_builtin_args
+  returns: void
+  description: You have found a bug if you can see this!
+  kwargs:
+    no_builtin_args:
+      type: bool
+      default: false
+      description: When set to `true`, the compiler arguments controlled by built-in configuration options are not added.
+
+- name: _name
+  returns: void
+  description: You have found a bug if you can see this!
+  kwargs:
+    name:
+      type: str
+      description: |
+        The name to use for printing a message about the compiler check.
+        If this keyword argument is not passed, no message will be printed about the check.
+
+# Even more convinient
+- name: _common
+  returns: void
+  description: You have found a bug if you can see this!
+  kwargs_inherit:
+    - compiler._args
+    - compiler._include_directories
+    - compiler._dependencies
+    - compiler._no_builtin_args
+    - compiler._prefix
+
+- name: _compiles
+  returns: void
+  description: You have found a bug if you can see this!
+  kwargs_inherit:
+    - compiler._args
+    - compiler._include_directories
+    - compiler._dependencies
+    - compiler._no_builtin_args
+    - compiler._name
+
+- name: _header
+  returns: void
+  description: You have found a bug if you can see this!
+  kwargs_inherit: compiler._common
+  kwargs:
+    required:
+      type: bool | feature
+      default: false
+      since: 0.50.0
+      description: If set to `true`, Meson will halt if the header check fails.
+
+
+# Star of the actual functions
+- name: version
+  returns: str
+  description: Returns the compiler's version number as a string.
+
+- name: cmd_array
+  returns: list[str]
+  description: Returns an array containing the command(s) for the compiler.
+
+
+- name: alignment
+  returns: int
+  description: Returns the alignment of the specified type.
+
+  posargs:
+    typename:
+      type: str
+      description: The name of the type to check.
+
+  kwargs_inherit:
+    - compiler._args
+    - compiler._prefix
+    - compiler._dependencies
+    # TODO: why not also allow passing `include_directories`?
+
+- name: run
+  returns: runresult
+  description: Attempts to compile and execute the given code fragment.
+  posargs_inherit: compiler._code
+  kwargs_inherit: compiler._compiles
+
+- name: get_id
+  returns: str
+  description: |
+    Returns a string identifying the compiler.
+    For example, `gcc`, `msvc`, [and more](Reference-tables.md#compiler-ids).
+
+- name: get_linker_id
+  returns: str
+  since: 0.53.0
+  description: |
+    Returns a string identifying the linker.
+    For example, `ld.bfd`, `link`, [and more](Reference-tables.md#linker-ids).
+
+- name: symbols_have_underscore_prefix
+  returns: bool
+  since: 0.37.0
+  description: Returns `true` if the C symbol mangling is one underscore (`_`) prefixed to the symbol.
+
+- name: has_member
+  returns: bool
+  description: Returns true if the type has the specified member.
+  kwargs_inherit: compiler._common
+  posargs:
+    typename:
+      type: str
+      description: The type to check.
+    membername:
+      type: str
+      description: The member to check.
+
+- name: has_members
+  returns: bool
+  description: Returns `true` if the type has *all* the specified members.
+  kwargs_inherit: compiler._common
+  posargs:
+    typename:
+      type: str
+      description: The type to check.
+  varargs:
+    name: member
+    type: str
+    min_varargs: 1
+    description: The members to check
+
+- name: has_function
+  returns: bool
+  description: |
+    Returns true if the given function is provided
+    by the standard library or a library passed in with the `args` keyword.
+
+  kwargs_inherit: compiler._common
+  posargs:
+    funcname:
+      type: str
+      description: The function to check.
+
+- name: has_type
+  returns: bool
+  description: Returns `true` if the specified token is a type.
+  kwargs_inherit: compiler._common
+  posargs:
+    typename:
+      type: str
+      description: The type to check.
+
+- name: compute_int
+  returns: int
+  since: 0.40.0
+  kwargs_inherit: compiler._common
+  description: |
+    Computes the value of the given expression
+    (as an example `1 + 2`). When cross compiling this is evaluated with
+    an iterative algorithm, you can specify keyword arguments `low`
+    (defaults to -1024), `high` (defaults to 1024) and `guess` to
+    specify max and min values for the search and the value to try
+    first.
+
+  posargs:
+    expr:
+      type: str
+      description: The expression to compute.
+
+  kwargs:
+    low:
+      type: int
+      default: -1024
+      description: The min value.
+    high:
+      type: int
+      default: 1024
+      description: The max value.
+    guess:
+      type: int
+      description: The value to try first.
+
+- name: sizeof
+  returns: int
+  description: returns the size of the given type (e.g. `'int'`) or -1 if the type is unknown.
+  kwargs_inherit: compiler._common
+  posargs:
+    typename:
+      type: str
+      description: The type to compute.
+
+- name: get_define
+  returns: str
+  since: 0.40.0
+  description: |
+    Returns the given preprocessor symbol's value
+    as a string or empty string if it is not defined.
+
+    *(since 0.47.0)* This method will concatenate string literals as
+    the compiler would. E.g. `"a" "b"` will become `"ab"`.
+
+  kwargs_inherit: compiler._common
+  posargs:
+    definename:
+      type: str
+      description: The define to check.
+
+- name: compiles
+  returns: bool
+  description: Returns true if the code compiles.
+  posargs_inherit: compiler._code
+  kwargs_inherit: compiler._compiles
+
+- name: links
+  returns: bool
+  description: Returns true if the code compiles and links.
+  posargs_inherit: compiler._code
+  kwargs_inherit: compiler._compiles
+
+- name: check_header
+  returns: bool
+  since: 0.47.0
+  description: |
+    Returns true if the specified header is *usable*
+    with the specified prefix, dependencies, and arguments.
+
+  kwargs_inherit: compiler._header
+  posargs:
+    header_name:
+      type: str
+      description: The header to check.
+
+- name: has_header
+  returns: bool
+  description: |
+    Returns true if the specified header is *exists*
+    with the specified prefix, dependencies, and arguments.
+
+    This method is faster than [[compiler.check_header]] since it only does a
+    pre-processor check.
+
+  kwargs_inherit: compiler._header
+  posargs_inherit: compiler.check_header
+
+- name: has_header_symbol
+  returns: bool
+  description: |
+    Detects whether a particular symbol is declared in the specified header.
+
+    Symbols here include function, variable, `#define`, type definition, etc.
+
+  kwargs_inherit: compiler._header
+  posargs:
+    heade:
+      type: str
+      description: The header to check.
+    symbol:
+      type: str
+      description: The symbol to check.
+
+- name: find_library
+  returns: dep
+  description: Tries to find the library specified in the positional argument.
+
+  kwargs_inherit: compiler._common
+  kwargs:
+    required:
+      type: bool | feature
+      default: true
+      description: |
+        If set `true`, Meson will abort with an error if the library could not
+        be found. Otherwise, Meson will continue and the found method of the
+        returned object will return `false`.
+
+        *(since 0.47.0)* The value of a [`feature`](Build-options.md#features)
+        option can also be passed here.
+
+    has_headers:
+      type: list[str]
+      since: 0.50.0
+      description: |
+        List of headers that must be found as well.
+        This is check is equivalent to checking each herader with an
+        [[compiler.has_header]] call.
+
+    static:
+      type: bool
+      default: false
+      since: 0.51.0
+      description: |
+        If `true`, the search is limited to static libraries only.
+        Setting this value to `false` (the default) will search for both shared
+        *and* static libraries.
+
+    disabler:
+      type: bool
+      default: false
+      since: 0.49.0
+      description: If `true`, this method will return a [[@disabler]] on a failed check.
+
+    dirs:
+      type: list[str]
+      description: |
+        Additional directories to search in.
+
+        By default the library is searched for in the system library directory
+        (e.g. /usr/lib). Specifying more directories here, causes Meson to search
+        in those directories as well as the system directories.
+
+
+# Compiler arguments
+- name: has_argument
+  returns: bool
+  description: |
+    Returns `true` if the compiler accepts the specified command line argument,
+    that is, can compile code without erroring out or printing a warning about
+    an unknown flag.
+
+  posargs:
+    argument:
+      type: str
+      description: The argument to check.
+
+- name: has_multi_arguments
+  since: 0.37.0
+  returns: bool
+  description: |
+    the same as [[compiler.has_argument]] but takes multiple arguments
+    and uses them all in a single compiler invocation.
+
+  varargs:
+    name: arg
+    type: str
+    description: The arguments to check.
+
+- name: get_supported_arguments
+  returns: list[str]
+  since: 0.43.0
+  varargs_inherit: compiler.has_multi_arguments
+  description: |
+    Returns an array containing only the arguments supported by the compiler,
+    as if [[compiler.has_argument]] were called on them individually.
+
+  kwargs:
+    checked:
+      type: str
+      since: 0.59.0
+      default: "'off'"
+      description: |
+        Supported values:
+          - `'off'`: Quietely ignore unsupported arguments
+          - `'warn'`: Print a warning for unsupported arguments
+          - `'require'`: Abort if at least one argument is not supported
+
+- name: first_supported_argument
+  returns: list[str]
+  since: 0.43.0
+  varargs_inherit: compiler.has_multi_arguments
+  description: |
+    Given a list of strings, returns the first argument that passes the
+    [[compiler.has_argument]] test or an empty array if none pass.
+
+
+# Linker arguments
+- name: has_link_argument
+  since: 0.46.0
+  returns: bool
+  description: |
+    Returns `true` if the linker accepts the specified command line argument,
+    that is, can
+    compile and link code without erroring out or printing a warning
+    about an unknown flag. Link arguments will be passed to the
+    compiler, so should usually have the `-Wl,` prefix. On VisualStudio
+    a `/link` argument will be prepended.
+
+  posargs:
+    argument:
+      type: str
+      description: The argument to check.
+
+- name: has_multi_link_arguments
+  since: 0.46.0
+  returns: bool
+  description: |
+    the same as [[compiler.has_link_argument]] but takes multiple arguments
+    and uses them all in a single compiler invocation.
+
+  varargs:
+    name: arg
+    type: str
+    description: The link arguments to check.
+
+- name: get_supported_link_arguments
+  returns: list[str]
+  since: 0.46.0
+  varargs_inherit: compiler.has_multi_link_arguments
+  description: |
+    Returns an array containing only the arguments supported by the compiler,
+    as if [[compiler.has_link_argument]] were called on them individually.
+
+  # TODO: why is this not present here?
+  # kwargs:
+  #   checked:
+  #     type: str
+  #     sinec: 0.59.0
+  #     default: "'off'"
+  #     description: |
+  #       Supported values:
+  #         - `'off'`: Quietely ignore unsupported arguments
+  #         - `'warn'`: Print a warning for unsupported arguments
+  #         - `'require'`: Abort if at least one argument is not supported
+
+- name: first_supported_link_argument
+  returns: list[str]
+  since: 0.46.0
+  varargs_inherit: compiler.has_multi_link_arguments
+  description: |
+    Given a list of strings, returns the first argument that passes the
+    [[compiler.has_link_argument]] test or an empty array if none pass.
+
+
+
+
+
+- name: has_function_attribute
+  returns: bool
+  since: 0.48.0
+  description: |
+    Returns `true` if the compiler supports the GNU style (`__attribute__(...)`) `name`.
+    This is preferable to manual compile checks as it may be optimized for compilers that
+    do not support such attributes.
+    [This table](Reference-tables.md#gcc-__attribute__) lists all of the supported attributes.
+
+  posargs:
+    name:
+      type: str
+      description: The attribute nane to check.
+
+- name: get_supported_function_attributes
+  returns: list[str]
+  since: 0.48.0
+  description: |
+    Returns an array containing any names that are supported GCC style attributes.
+    Equivalent to [[compiler.has_function_attribute]] was called on each of
+    them individually.
+
+  # TODO: Again why doesn't this function have the checked kwarg?
+
+- name: get_argument_syntax
+  returns: str
+  since: 0.49.0
+  description: |
+    returns a string identifying the type of arguments the compiler takes.
+    Can be one of `gcc`, `msvc`, or an undefined
+    string value. This method is useful for identifying compilers that are not
+    gcc or msvc, but use the same argument syntax as one of those two compilers
+    such as clang or icc, especially when they use different syntax on different
+    operating systems.
diff --git a/docs/yaml/objects/custom_idx.yaml b/docs/yaml/objects/custom_idx.yaml
new file mode 100644
index 0000000..68440ba
--- /dev/null
+++ b/docs/yaml/objects/custom_idx.yaml
@@ -0,0 +1,15 @@
+name: custom_idx
+long_name: Custom target index
+description: References a specific output file of a [[@custom_tgt]] object.
+
+methods:
+  - name: full_path
+    returns: str
+    since: 0.54.0
+    description: |
+      Returns a full path pointing to the result target file
+      NOTE: In most cases using the object itself will do the same job as
+      this and will also allow Meson to setup inter-target dependencies
+      correctly. Please file a bug if that doesn't work for you.
+
+      See [[custom_tgt.full_path]]
diff --git a/docs/yaml/objects/custom_tgt.yaml b/docs/yaml/objects/custom_tgt.yaml
new file mode 100644
index 0000000..5102ab9
--- /dev/null
+++ b/docs/yaml/objects/custom_tgt.yaml
@@ -0,0 +1,33 @@
+name: custom_tgt
+long_name: Custom target
+extends: tgt
+description: |
+  This object is returned by [[custom_target]] and contains a target with the following methods:
+
+methods:
+  - name: full_path
+    returns: str
+    description: |
+      Returns a full path pointing to the result target file
+      NOTE: In most cases using the object itself will do the same job as
+      this and will also allow Meson to setup inter-target dependencies
+      correctly. Please file a bug if that doesn't work for you.
+      *(since 0.54.0)* It can be also called on indexes objects:
+      `custom_targets[i].full_path()`.
+
+  - name: "[index]"
+    returns: custom_idx
+    description: |
+      Returns an opaque object that references this target, and
+      can be used as a source in other targets. When it is used as such it
+      will make that target depend on this custom target, but the only
+      source added will be the one that corresponds to the index of the
+      custom target's output argument.
+
+  - name: to_list
+    returns: list[custom_idx]
+    since: 0.54.0
+    description: |
+        Returns a list of opaque objects that references this target,
+        and can be used as a source in other targets. This can be used to
+        iterate outputs with `foreach` loop.
diff --git a/docs/yaml/objects/dep.yaml b/docs/yaml/objects/dep.yaml
new file mode 100644
index 0000000..23092c2
--- /dev/null
+++ b/docs/yaml/objects/dep.yaml
@@ -0,0 +1,212 @@
+name: dep
+long_name: Dependency object
+description: Abstract representation of a dependency
+
+methods:
+  - name: found
+    returns: bool
+    description: Returns whether the dependency was found.
+
+  - name: name
+    since: 0.48.0
+    returns: str
+    description: |
+      Returns the name of the dependency that was searched.
+      Returns `'internal'` for dependencies created with
+      [[declare_dependency]].
+
+  - name: get_pkgconfig_variable
+    since: 0.36.0
+    deprecated: 0.56.0
+    returns: str
+    description: |
+      Gets the pkg-config variable specified,
+      or, if invoked on a non pkg-config
+      dependency, error out.
+
+    posargs:
+      var_name:
+        type: str
+        description: Name of the variable to query
+
+    kwargs:
+      define_variable:
+        type: list[str]
+        since: 0.44.0
+        description: |
+          You can also redefine a
+          variable by passing a list to this kwarg
+          that can affect the retrieved variable: `['prefix', '/'])`.
+
+      default:
+        type: str
+        since: 0.45.0
+        description: |
+          The value to return if the variable was not found.
+          A warning is issued if the variable is not defined and this kwarg is not set.
+
+  - name: get_configtool_variable
+    since: 0.44.0
+    deprecated: 0.56.0
+    returns: str
+    description: |
+      Gets the command line argument from the config tool (with `--` prepended), or,
+      if invoked on a non config-tool dependency, error out.
+
+    posargs:
+      var_name:
+        type: str
+        description: Name of the variable to query
+
+  - name: type_name
+    returns: str
+    description: |
+      Returns a string describing the type of the
+      dependency, the most common values are `internal` for deps created
+      with [[declare_dependency]] and `pkgconfig` for system dependencies
+      obtained with Pkg-config.
+
+  - name: version
+    returns: str
+    description: |
+      the version number as a string,
+      for example `1.2.8`.
+      `unknown` if the dependency provider doesn't support determining the
+      version.
+
+  - name: include_type
+    returns: str
+    since: 0.52.0
+    description: Returns the value set by the `include_type` kwarg.
+
+  - name: as_system
+    returns: dep
+    since: 0.52.0
+    description: |
+      Returns a copy of the dependency object, which has changed the value of `include_type`
+      to `value`. The `value` argument is optional and
+      defaults to `'preserve'`.
+
+    optargs:
+      value:
+        type: str
+        description: The new value. See [[dependency]] for supported values.
+
+  - name: as_link_whole
+    returns: dep
+    since: 0.56.0
+    description: |
+      Only dependencies created with [[declare_dependency]],
+      returns a copy of the dependency object with all
+      link_with arguments changed to link_whole. This is useful for example for
+      fallback dependency from a subproject built with `default_library=static`.
+      Note that all `link_with` objects must be static libraries otherwise an error
+      will be raised when trying to `link_whole` a shared library.
+
+  - name: partial_dependency
+    returns: dep
+    since: 0.46.0
+    description: |
+      Returns a new dependency object with the same name, version, found status,
+      type name, and methods as the object that called it. This new
+      object will only inherit other attributes from its parent as
+      controlled by keyword arguments.
+
+      If the parent has any dependencies, those will be applied to the new
+      partial dependency with the same rules. So, given:
+
+      ```meson
+      dep1 = declare_dependency(compile_args : '-Werror=foo', link_with : 'libfoo')
+      dep2 = declare_dependency(compile_args : '-Werror=bar', dependencies : dep1)
+      dep3 = dep2.partial_dependency(compile_args : true)
+      ```
+
+      dep3 will add `['-Werror=foo', '-Werror=bar']` to the compiler args
+      of any target it is added to, but libfoo will not be added to the
+      link_args.
+
+      The following arguments will add the following attributes:
+
+      - compile_args: any arguments passed to the compiler
+      - link_args: any arguments passed to the linker
+      - links: anything passed via link_with or link_whole
+      - includes: any include_directories
+      - sources: any compiled or static sources the dependency has
+
+    warnings:
+      - A bug present until 0.50.1 results in the above behavior
+        not working correctly.
+
+    kwargs:
+      compile_args:
+        type: bool
+        default: false
+        description: Whether to include compile_args
+
+      link_args:
+        type: bool
+        default: false
+        description: Whether to include link_args
+
+      links:
+        type: bool
+        default: false
+        description: Whether to include links
+
+      includes:
+        type: bool
+        default: false
+        description: Whether to include includes
+
+      sources:
+        type: bool
+        default: false
+        description: Whether to include sources
+
+  - name: get_variable
+    returns: str
+    since: 0.51.0
+    description: |
+      A generic variable getter method, which replaces the
+      `get_*type*_variable` methods. This allows one to get the variable
+      from a dependency without knowing specifically how that dependency
+      was found. If `default_value` is set and the value cannot be gotten
+      from the object then `default_value` is returned, if it is not set
+      then an error is raised.
+
+    optargs:
+      varname:
+        type: str
+        since: 0.58.0
+        description: |
+          This argument is used as a default value
+          for `cmake`, `pkgconfig`, `configtool` and `internal` keyword
+          arguments. It is useful in the common case where `pkgconfig` and `internal`
+          use the same variable name, in which case it's easier to write `dep.get_variable('foo')`
+          instead of `dep.get_variable(pkgconfig: 'foo', internal: 'foo')`.
+
+    kwargs:
+      cmake:
+        type: str
+        description: The CMake variable name
+
+      pkgconfig:
+        type: str
+        description: The pkgconfig variable name
+
+      configtool:
+        type: str
+        description: The configtool variable name
+
+      internal:
+        type: str
+        since: 0.54.0
+        description: The internal variable name
+
+      default_value:
+        type: str
+        description: The davault value to return when the variable does not exist
+
+      pkgconfig_define:
+        type: list[str]
+        description: See [[dep.get_pkgconfig_variable]]
diff --git a/docs/yaml/objects/disabler.yaml b/docs/yaml/objects/disabler.yaml
new file mode 100644
index 0000000..bd785bb
--- /dev/null
+++ b/docs/yaml/objects/disabler.yaml
@@ -0,0 +1,13 @@
+name: disabler
+long_name: Disabler
+description: |
+  A disabler object is an object that behaves in much the same way as
+  NaN numbers do in floating point math. That is when used in any
+  statement (function call, logical op, etc) they will cause the
+  statement evaluation to immediately short circuit to return a disabler
+  object. A disabler object has one method:
+
+methods:
+- name: found
+  returns: bool
+  description: Always returns `false`
diff --git a/docs/yaml/objects/env.yaml b/docs/yaml/objects/env.yaml
new file mode 100644
index 0000000..fea11d5
--- /dev/null
+++ b/docs/yaml/objects/env.yaml
@@ -0,0 +1,85 @@
+name: env
+long_name: Environment
+description: |
+  This object is returned by [[environment]] and stores
+  detailed information about how environment variables should be set
+  during tests. It should be passed as the `env` keyword argument to
+  tests and other functions.
+
+  *Since 0.58.0* [[env.append]] and [[env.prepend]] can be called multiple times
+  on the same `varname`. Earlier Meson versions would warn and only the last
+  operation took effect.
+
+example: |
+  ```meson
+  env = environment()
+
+  # MY_PATH will be '0:1:2:3'
+  env.set('MY_PATH', '1')
+  env.append('MY_PATH', '2')
+  env.append('MY_PATH', '3')
+  env.prepend('MY_PATH', '0')
+  ```
+
+methods:
+- name: append
+  returns: void
+  description: |
+    appends the given values to
+    the old value of the environment variable, e.g.  `env.append('FOO',
+    'BAR', 'BAZ', separator : ';')` produces `BOB;BAR;BAZ` if `FOO` had
+    the value `BOB` and plain `BAR;BAZ` if the value was not defined.
+
+  posargs:
+    variable:
+      type: str
+      description: The variable to modify
+
+  varargs:
+    type: str
+    name: Value
+    description: The values to append
+
+  kwargs:
+    separator:
+      type: str
+      description: |
+        The seperator to use. If not explicitly specified, the default path
+        separator for the host operating system will be used, i.e. ';' for
+        Windows and ':' for UNIX/POSIX systems.
+
+- name: prepend
+  returns: void
+  description: Same as `append` except that it writes to the beginning of the variable.
+
+  posargs:
+    variable:
+      type: str
+      description: The variable to modify
+
+  varargs:
+    type: str
+    name: Value
+    description: The values to prepend
+
+  kwargs_inherit: env.append
+
+- name: set
+  returns: void
+  description: |
+    Sets the environment variable
+    specified in the first argument to the values in the varargs
+    joined by the separator. For instance, `env.set('FOO', 'BAR'),` sets envvar
+    `FOO` to value `BAR`.
+
+  posargs:
+    variable:
+      type: str
+      description: The variable to modify
+
+  varargs:
+    type: str
+    name: Value
+    description: The values to set
+
+  kwargs_inherit: env.append
diff --git a/docs/yaml/objects/exe.yaml b/docs/yaml/objects/exe.yaml
new file mode 100644
index 0000000..c7be05b
--- /dev/null
+++ b/docs/yaml/objects/exe.yaml
@@ -0,0 +1,4 @@
+name: exe
+long_name: Executable target
+description: An executable
+extends: build_tgt
diff --git a/docs/yaml/objects/external_program.yaml b/docs/yaml/objects/external_program.yaml
new file mode 100644
index 0000000..d0e476f
--- /dev/null
+++ b/docs/yaml/objects/external_program.yaml
@@ -0,0 +1,3 @@
+name: external_program
+long_name: External program
+description: TODO
diff --git a/docs/yaml/objects/extracted_obj.yaml b/docs/yaml/objects/extracted_obj.yaml
new file mode 100644
index 0000000..c418faf
--- /dev/null
+++ b/docs/yaml/objects/extracted_obj.yaml
@@ -0,0 +1,3 @@
+name: extracted_obj
+long_name: Extracted object file
+description: Opaque object representing extracted object files from build targets
diff --git a/docs/yaml/objects/feature.yaml b/docs/yaml/objects/feature.yaml
new file mode 100644
index 0000000..5b451e5
--- /dev/null
+++ b/docs/yaml/objects/feature.yaml
@@ -0,0 +1,70 @@
+name: feature
+long_name: Feature option object
+since: 0.47.0
+description: Meson object representing a [`feature` options](Build-options.md#features)
+
+methods:
+- name: enabled
+  returns: bool
+  description: Returns whether the feature was set to `'enabled'`
+
+- name: disabled
+  returns: bool
+  description: Returns whether the feature was set to `'disabled'`
+
+- name: auto
+  returns: bool
+  description: Returns whether the feature was set to `'auto'`
+
+- name: allowed
+  since: 0.59.0
+  returns: bool
+  description: Returns whether the feature was set to `'enabled'` or `'auto'`
+
+- name: disable_auto_if
+  since: 0.59.0
+  returns: feature
+  description: |
+    Returns the feature, with `'auto'` converted to `'disabled'` if value is true.
+
+    | Feature / Condition | `value = true` | `value = false` |
+    | ------------------- | -------------- | --------------- |
+    | Enabled             | Enabled        | Enabled         |
+    | Disabled            | Disabled       | Disabled        |
+    | Auto                | Disabled       | Auto            |
+
+  posargs:
+    value:
+      type: bool
+      description: See the table above
+
+- name: require
+  returns: feature
+  since: 0.59.0
+  description: |
+    Returns the object itself if the value is true; an error if the object is
+    `'enabled'` and the value is false; a disabled feature if the object
+    is `'auto'` or `'disabled'` and the value is false.
+
+  example: |
+    `require` is useful to restrict the applicability of `'auto'` features,
+    for example based on other features or on properties of the host machine:
+
+    ```
+    if get_option('directx').require(host_machine.system() == 'windows',
+          error_message: 'DirectX only available on Windows').allowed() then
+      src += ['directx.c']
+      config.set10('HAVE_DIRECTX', 1)
+    endif
+    ```
+
+  posargs:
+    value:
+      type: bool
+      description: The value to check
+
+  kwargs:
+    error_message:
+      type: str
+      default: "''"
+      description: The error Message to print if the check fails
diff --git a/docs/yaml/objects/file.yaml b/docs/yaml/objects/file.yaml
new file mode 100644
index 0000000..6aa0b85
--- /dev/null
+++ b/docs/yaml/objects/file.yaml
@@ -0,0 +1,3 @@
+name: file
+long_name: File
+description: Opaque object that stores the path to an existing file
diff --git a/docs/yaml/objects/generated_list.yaml b/docs/yaml/objects/generated_list.yaml
new file mode 100644
index 0000000..7d1fe61
--- /dev/null
+++ b/docs/yaml/objects/generated_list.yaml
@@ -0,0 +1,3 @@
+name: generated_list
+long_name: Generated list object
+description: Opaque object representing the result of a [[generator.process]] call.
diff --git a/docs/yaml/objects/generator.yaml b/docs/yaml/objects/generator.yaml
new file mode 100644
index 0000000..e7b866a
--- /dev/null
+++ b/docs/yaml/objects/generator.yaml
@@ -0,0 +1,36 @@
+name: generator
+long_name: Generator object
+description: |
+  This object is returned by [[generator]] and contains a
+  generator that is used to transform files from one type to another by
+  an executable (e.g. `idl` files into source code and headers).
+
+methods:
+  - name: process
+    returns: generated_list
+    description: |
+      Takes a list of files, causes them to be processed and returns an object containing the result
+      which can then, for example, be passed into a build target definition.
+
+    varargs:
+      name: source
+      min_varargs: 1
+      type: str | file | custom_tgt | custom_idx | generated_list
+      description: List of sources to process.
+
+    kwargs:
+      extra_args:
+        type: list[str]
+        description: |
+          If present, will be used to replace an entry `@EXTRA_ARGS@` in the argument list.
+
+      preserve_path_from:
+        type: str
+        since: 0.45.0
+        description: |
+          If given, specifies that the output files need to maintain their directory structure
+          inside the target temporary directory. The most common value for this is
+          `meson.current_source_dir()`. With this value when a file called
+          `subdir/one.input` is processed it generates a file `{target private
+          directory}/subdir/one.out` as opposed to `{target private
+          directory}/one.out`.
diff --git a/docs/yaml/objects/inc.yaml b/docs/yaml/objects/inc.yaml
new file mode 100644
index 0000000..9f5e684
--- /dev/null
+++ b/docs/yaml/objects/inc.yaml
@@ -0,0 +1,3 @@
+name: inc
+long_name: Include directories
+description: Opaque wrapper for storing include directories
diff --git a/docs/yaml/objects/jar.yaml b/docs/yaml/objects/jar.yaml
new file mode 100644
index 0000000..14e79ae
--- /dev/null
+++ b/docs/yaml/objects/jar.yaml
@@ -0,0 +1,4 @@
+name: jar
+long_name: JAR build target
+description: A Java JAR build target
+extends: build_tgt
diff --git a/docs/yaml/objects/lib.yaml b/docs/yaml/objects/lib.yaml
new file mode 100644
index 0000000..da28489
--- /dev/null
+++ b/docs/yaml/objects/lib.yaml
@@ -0,0 +1,4 @@
+name: lib
+long_name: Library target
+extends: build_tgt
+description: Represents either a shared or static library
diff --git a/docs/yaml/objects/module.yaml b/docs/yaml/objects/module.yaml
new file mode 100644
index 0000000..cd98faa
--- /dev/null
+++ b/docs/yaml/objects/module.yaml
@@ -0,0 +1,13 @@
+name: module
+long_name: Imported module object
+description: |
+  Base type for all modules.
+
+  Modules provide their own specific implementation methods, but all modules
+  proivide the following methods:
+
+methods:
+- name: found
+  returns: bool
+  since: 0.59.0
+  description: Returns `true` if the module was successfully imported, otherwise `false`.
diff --git a/docs/yaml/objects/range.yaml b/docs/yaml/objects/range.yaml
new file mode 100644
index 0000000..bc9e981
--- /dev/null
+++ b/docs/yaml/objects/range.yaml
@@ -0,0 +1,4 @@
+name: range
+long_name: Range object
+since: 0.58.0
+description: Opaque object that can be used in a loop and accessed via `[num]`.
diff --git a/docs/yaml/objects/run_tgt.yaml b/docs/yaml/objects/run_tgt.yaml
new file mode 100644
index 0000000..7805878
--- /dev/null
+++ b/docs/yaml/objects/run_tgt.yaml
@@ -0,0 +1,4 @@
+name: run_tgt
+long_name: Run target
+description: Opaque object returned by [[run_target]].
+extends: tgt
diff --git a/docs/yaml/objects/runresult.yaml b/docs/yaml/objects/runresult.yaml
new file mode 100644
index 0000000..36079a3
--- /dev/null
+++ b/docs/yaml/objects/runresult.yaml
@@ -0,0 +1,26 @@
+name: runresult
+long_name: Run result object
+description: |
+  This object encapsulates the result of trying to compile and run a
+  sample piece of code with [[compiler.run]] or
+  [[run_command]].
+
+methods:
+- name: compiled
+  returns: bool
+  description: |
+    If `true`, the compilation succeeded, if `false` it did not
+    and the other methods return unspecified data. This is only available
+    for `compiler.run()` results.
+
+- name: returncode
+  returns: int
+  description: The return code of executing the compiled binary
+
+- name: stderr
+  returns: str
+  description: The standard error produced when the command was run.
+
+- name: stdout
+  returns: str
+  description: The standard out produced when the command was run.
diff --git a/docs/yaml/objects/subproject.yaml b/docs/yaml/objects/subproject.yaml
new file mode 100644
index 0000000..d84e3f0
--- /dev/null
+++ b/docs/yaml/objects/subproject.yaml
@@ -0,0 +1,30 @@
+name: subproject
+long_name: Subproject object
+description: This object is returned by [[subproject]] and is an opaque object representing it.
+
+methods:
+- name: found
+  returns: bool
+  since: 0.48.0
+  description: Returns whether the subproject was successfully setup.
+
+- name: get_variable
+  returns: any
+  description: |
+    fetches the specified variable from inside the subproject.
+    This is useful to, for instance, get a
+    [[declare_dependency]] from the [subproject](Subprojects.md).
+
+    If the variable does not exist, the variable `fallback` is returned.
+    If a fallback is not specified, then attempting to read a non-existing
+    variable will cause a fatal error.
+
+  posargs:
+    var_name:
+      type: str
+      description: The name of the variable to query
+
+  optargs:
+    fallback:
+      type: any
+      description: The fallback value to return if `var_name` does not exist.
diff --git a/docs/yaml/objects/tgt.yaml b/docs/yaml/objects/tgt.yaml
new file mode 100644
index 0000000..c0d0285
--- /dev/null
+++ b/docs/yaml/objects/tgt.yaml
@@ -0,0 +1,3 @@
+name: tgt
+long_name: Meson Target
+description: Opaque base object for all Meson targets