參考手冊

參考手冊 是從 docs/yaml 中的 YAML 檔案自動產生的。這讓 Meson 專案能夠強制執行參考手冊的一致風格，並更容易對產生的 Markdown 檔案進行樣式變更，而無需觸及實際的文件。此外，還可以支援多個產生後端（除了 mesonbuild.com 的 Markdown 產生器之外）。

讀取這些 YAML 檔案的產生器位於 docs/refman 中，主執行檔為 docs/genrefman.py。預設情況下，genrefman.py 將會使用嚴格的 YAML 子集來載入 YAML 手冊，但代價是載入速度較慢。您可以選擇性地使用 fastyaml 載入器來停用所有這些安全檢查，這將會大幅加快速度，但代價是正確性較低。

genrefman 腳本需要下列 Python 套件

• chevron
• strictyaml

連結至參考手冊

使用類似這樣的標籤 [[<tag>]]，可以在 Meson 文件中的任何地方插入連結至參考手冊的連結。這保證了連結保持穩定（即使參考手冊的結構發生變化），並且在任何地方都使用統一的格式。

要連結到函式，應該將函式名稱放入標籤中：[[<func name>]]。方法（適用於所有種類的物件，包括模組）可以像這樣連結：[[<object name>.<method name>]]。要連結到物件本身，可以使用 [[@<object name>]] 語法。

這些標籤不需要放在行內程式碼中！Hotdoc 擴充功能會在此處理格式設定。如果需要放置標籤（例如，將參考直接包含在程式碼區塊中），則應使用 [[#<remaining tag>]] 語法。

範例

• 函式：executable()
• 方法：meson.version()
• 物件：str

現在在程式碼區塊中使用相同的範例

str executable('main', [
    'file_@0@.cpp'.format(meson.version())
])

目錄結構

docs/yaml 下的目錄結構非常重要，因為它決定了 YAML 檔案的解譯方式

• builtins：內建物件（例如 meson）的文件
• elementary：字串、清單、整數、void 等等。
• objects：所有由函式和方法傳回的物件，但不包括模組
• functions：所有根 Meson 函式（executable()、project() 等等）

最後，模組定義在 modules 子目錄中。在這裡，每個模組都有自己的目錄。模組本身必須在名為 module.yaml 的檔案中。然後，模組傳回的所有物件都位於此檔案的旁邊。

YAML 檔案本身的名稱會被忽略（module.yaml 除外），且不具有任何特定意義。但是，建議以物件的 name 條目來命名 YAML 檔案。

所有名稱以 _ 開頭的物件和函式都會被標記為私有，且不會匯出到最終文件中。這些檔案的主要目的是簡化函式和引數的繼承。

YAML 架構

YAML 檔案本身的結構如下

函式

name: executable     # The name of the function                [required]
returns: build_tgt   # Must be a `name` of an existing object  [required]
description: |
  The first line until the first dot of the description is the brief.
  All other lines are not part of the brief and should document the function

  Here the full Markdown syntax is supported, such as links, `inline code`,
  code blocks, and references to other parts of the Reference Manual: str.

  This is true for **all** description keys in all YAML files. Defining a
  description is **always** required.

since:      0.42.0       # A valid Meson version
deprecated: 100.99.0     # A valid Meson version

example: |
  Similar to `description`, but is put under a different section and should
  contain an example.

notes:
- A list of notes that should stand out.
- Should be used sparingly.
- Notes are optional.

warnings:
- Similar to notes, but a warning
- Warnings are also optional.


# To avoid duplicating documentation / code, argument inheritance is supported with
# the following optional keys:

posargs_inherit: _build_target_base  # Use the posargs definition of `_build_target_base` here
optargs_inherit: _build_target_base  # Use the optargs definition of `_build_target_base` here
varargs_inherit: _build_target_base  # Use the varargs definition of `_build_target_base` here
kwargs_inherit: _build_target_base   # Add all kwargs of `_build_target_base` to this function

# Whether argument flattening (see Syntax.md) is enabled
# for this function. Defaults to `true`.
args_flattening: true

posargs:
  arg_name:
    type: bool | dep           # [required]
    description: Some text.    # [required]
    since: 0.42.0
    deprecated: 100.99.0
    default: false             # Is technically supported buy should **not** be used for posargs

  another_arg:
    ...

optargs:
  optional_arg:
    type: int                  # [required]
    description: Hello World   # [required]
    since: 0.42.0
    deprecated: 100.99.0
    default: false             # Default values can make sense here

  next_arg:
    ...

varargs:
  name: Some name                # [required]
  type: str | list[str | int]    # [required]
  description: Some helpful text # [required]
  since: 0.42.0
  deprecated: 100.99.0
  min_varargs: 1
  max_varargs: 21


kwargs:
  kwarg_name:
    type: str                      # [required]
    description: Meson is great!   # [required]
    since: 0.42.0
    deprecated: 100.99.0
    default: false
    required: false                # Some kwargs may be required

物件

name: build_tgt                       # [required]
long_name: Build target               # [required]
description: Just some description.   # [required]
example: Same as for functions

# Objects can be marked as containers. In this case they can be used in a `type`
# like this `container[held | objects]`. Currently this only makes sense for
# lists and dicts. There is almost no reason to set this to true for other objects.
is_container: true

since:      0.42.0
deprecated: 100.99.0

# Notes and warnings work the same as with functions
notes:
warnings:

# Inheritance is also supported for objects. Here all methods from the parent
# object are inherited. The trick with `_private` objects also works here
# to help with more complex structures.
extends: tgt

# Methods are a list of functions (see the previous section).
methods:
- ...