如何贡献

基础

欢迎为这份 API 文档做出贡献。文档系统里有三类用户角色：

新注册的用户默认是贡献人员。注册后你会收到一封确认邮件，之后就可以开始编辑。

讨论

编辑页面时，可以在编辑框下方留下编辑评论。这是贡献者之间交流的方式，能让改进更顺畅。作为贡献者，你会看到作者和编辑人员发给你的评论通知，方便快速解决格式错误、拼写问题或复杂段落这类琐事。

与现有页面无关的问题，请使用 WordPress 仪表板（dashboard）上的聊天功能。

更广泛的讨论可以到 Klei 官方论坛的相关帖子进行。

格式约定

页面结构

不能在顶层菜单上直接添加页面。 每个页面都应标记为另一个页面的子页。所有顶层页面会显示在菜单上，子页面则收纳在下拉菜单中。

文档系统已经提供了大部分页面的模板。使用现有模板，或者新建页面后标记为某个页面的子页面。可以用下面的短代码显示当前页面的所有子页：

1
2

-- 不传参数则显示当前页面的所有子页面
[subpages depth="1" childof="286"]

贡献人员应提交修改供审查，作者负责审核并发布。

标题结构

绝对不要使用 <h1> 作为标题。表格中每一节的标题，包括其他描述，请在源码中使用 foo(argname1, arg2) 的形式定义，这样更易读。常见的、含义自明的关键词也可以直接用，比如 prefab、fn。

标题排列通常采用这样的层次：

• foo(bar)
  • local addFoo() — 仅在解释时有用，例如无法获得上述文本时
• bar(baz)
• 公共本地函数
  • raw(foo, bar, baz) — 仅当它在当前类/文件中确实公开时使用

对于更通用的 API 接口集合（如 ModUtil），会集中在一个文件中说明，并在若干页面里建立实例，例如页面名 PAGENAME/internal。

表格

每份 API 文档都需要展示字段和方法。使用 TablePress 插件创建格式良好的列表，在 TablePress 选项卡里操作。

表 id 的命名规则是 CLASSNAME_fields / CLASSNAME_methods，请严格遵守，这样便于维护。优先复制现有表格，如果有合适的模板就用现成的，不要新建。

字段示例

方法示例

如果文章较长，建议添加锚链接，方便回到各章节。用一个 <code>= foo</code> 表示函数的非 nil 默认值，用 <code>: Class[, type, type2]</code> 表示该类接受这些类型的参数。

Lua 代码

写 Lua 代码时使用 pre 标签，还可以高亮要引用的行：在 class 属性里写 mark:7,9-10。

1
2
3
4
5
6
7
8
9
10
11
12

<pre class="lang:lua mark:7,9-10 start:2" title="tests/rect.lua">
Rectangle = {area = 0, length = 0, breadth = 0}
function Rectangle:new (o,length,breadth)
  o = o or {}
  setmetatable(o, self)
  self.__index = self
  self.length = length or 0
  self.breadth = breadth or 0
  self.area = length*breadth;
  return o
end
</pre>

渲染效果如下：

1
2
3
4
5
6
7
8
9
10
11
12

-- Meta class
Rectangle = {area = 0, length = 0, breadth = 0}

function Rectangle:new (o, length, breadth)
  o = o or {}
  setmetatable(o, self)
  self.__index = self
  self.length = length or 0
  self.breadth = breadth or 0
  self.area = length * breadth
  return o
end

标题中的路径请以 data/scripts/ 或 mods/ 为相对路径。