如何撰写 API 参考文档
建立你需要撰写或更新的页面列表
API 参考一般会包含以下页面。你可以在我们的页面类型文章中找到更多关于每个页面包含的内容、示例和模板的细节。在你开始之前，你应该写下你应该创建的所有页面的清单。
概述页
接口页
构造函数页
方法页
属性页
事件页
概念/使用指南页
示例
备注：在本文中，我们将使用 Web 音频 API 作为示例。
概述页
概述页是用来描述 API 的作用、它的顶级接口、其他接口中包含的相关功能以及其他高层次的细节的单个页面。它的名称和路径名需要以 API 的名称命名，后接“API”作为结尾。它位于 API 参考的顶层，是 https://developer.mozilla.org/zh-CN/docs/Web/API 的直接子页面。
示例：
标题：Web Audio API
路径名：Web_Audio_API
URL：https://developer.mozilla.org/zh-CN/docs/Web/API/Web_Audio_API
接口页
每个接口也会有自己的页面，描述该接口的目的，列出任何成员（构造函数、方法、属性等），并显示它与哪些浏览器兼容。每个页面的名称和路径名应该是接口的名称，与规范中写的完全一样。每个页面都被放置在 API 参考的顶层，作为 https://developer.mozilla.org/zh-CN/docs/Web/API 的一个子页面。
示例：
标题：AudioContext
路径名：AudioContext
URL：https://developer.mozilla.org/zh-CN/docs/Web/API/AudioContext
标题：AudioNode
路径名：AudioNode
URL：https://developer.mozilla.org/zh-CN/docs/Web/API/AudioNode
备注：我们为接口中出现的每一个成员撰写文档。你应该牢记以下规则：
我们要为定义在实现该接口的对象原型上的方法（实例方法），以及定义在实际类本身上的方法（静态方法）撰写文档。在极少数情况下，如果它们都存在于同一个接口上，你应该把它们列在页面上的不同部分（静态方法/实例方法）。通常只有实例方法存在，在这种情况下，你可以把这些方法放在“Methods”标题下。
不必为接口的继承属性和方法撰写文档：它们被列在各自的父接口上。不过我们确实暗示了它们的存在。
我们确实为定义在 mixin 中的属性和方法撰写文档。请参阅混入的贡献指南了解更多细节。
如果存在特殊方法，如字符串化方法（toString()）和 JSON 化方法（toJSON()），也会列出。
如果存在具名的构造函数（如 HTMLImageElement 的 Image()），也会列出。
构造函数页
每个接口都有 0 个或 1 个构造函数，记录在接口页面的子页面上。它描述了构造函数的目的，并显示了其语法的样子、使用示例、浏览器兼容性信息等。它的路径名是构造函数的名称，与接口名称完全相同，标题是接口名称、点、构造函数名称，然后是括号。
示例：
标题：AudioContext.AudioContext()
路径名：AudioContext
URL：https://developer.mozilla.org/zh-CN/docs/Web/API/AudioContext/AudioContext
属性页
每个接口都有零个或多个属性，记录在接口页面的子页面上。每个页面都描述了该属性的目的，并显示了其语法的样子、使用示例、浏览器兼容性信息等。它的路径名是属性的名称，标题是接口名称、点，然后是属性名称。
示例：
标题：AudioContext.state
路径名：state
URL: https://developer.mozilla.org/zh-CN/docs/Web/API/AudioContext/state
方法页
每个接口都有零个或多个方法，记录在接口页面的子页面上。每个页面都描述了该方法的目的，并显示了其语法的样子、使用示例、浏览器兼容性信息等。它的路径名是方法的名称，标题是接口名称、点、方法名称，然后是括号。
示例：
标题：AudioContext.close()
路径名：close
URL：https://developer.mozilla.org/zh-CN/docs/Web/API/AudioContext/close
标题：AudioContext.createGain()
路径名：createGain
URL：https://developer.mozilla.org/zh-CN/docs/Web/API/AudioContext/createGain
事件页
事件页往往作为其目标接口的子页面，并使用 eventname_event 路径名，标题设置为 Interface：eventName 事件。
不要为 on 事件处理程序属性创建页面。在 eventName_event 页面上提及访问事件的两种方式。
示例：
标题：XRSession：end 事件
路径：end_event
URL：https://developer.mozilla.org/zh-CN/docs/Web/API/XRSession/end_event
概念/指南页
大多数 API 参考资料至少有一个指南，有时还有一个概念页与之配套。至少，一个 API 参考资料应该包含一个名为“Using name-of-api”的指南，它将提供一个关于如何使用 API 的基本指南。更复杂的 API 可能需要多个使用指南来解释如何使用 API 的不同方面。
如果需要，你也可以包括一篇名为“name-of-api concepts”的概念文章，它将提供与 API 相关的任何概念背后的理论解释，开发人员应该理解这些概念以有效使用它。
这些文章都应该作为 API 概述页面的子页面来创建。例如，Web 音频有四篇指南和一篇概念文章：
https://developer.mozilla.org/zh-CN/docs/Web/API/Web_Audio_API/Using_Web_Audio_API
https://developer.mozilla.org/zh-CN/docs/Web/API/Web_Audio_API/Visualizations_with_Web_Audio_API
https://developer.mozilla.org/zh-CN/docs/Web/API/Web_Audio_API/Web_audio_spatialization_basics
https://developer.mozilla.org/zh-CN/docs/Web/API/Web_Audio_API/Porting_webkitAudioContext_code_to_standards_based_AudioContext
https://developer.mozilla.org/zh-CN/docs/Web/API/Web_Audio_API/Basic_concepts_behind_Web_Audio_API
示例
你应该创建一些例子，至少展示 API 的最常见的使用情况。你可以把这些放在适当的地方，推荐的地方是 MDN GitHub 仓库。
把它们都列出来
创建一个所有这些子页面的列表是跟踪它们的一个好方法。比如说：
Web_Audio_API
AudioContext
AudioContext.currentTime
AudioContext.destination
AudioContext.listener
...
AudioContext.createBuffer()
AudioContext.createBufferSource()
...
AudioNode
AudioNode.context
AudioNode.numberOfInputs
AudioNode.numberOfOutputs
...
AudioNode.connect(Param)
...
AudioParam
Events (update list)
start
end
…
列表中的每个接口都有一个单独的页面，作为 https://developer.mozilla.org/zh-CN/docs/Web/API 的子页面；例如，AudioContext的文件将位于 https://developer.mozilla.org/zh-CN/docs/Web/API/AudioContext。每个接口页解释该接口的作用，并提供构成该接口的方法和属性的列表。然后每个方法和属性都被记录在自己的页面上，该页面被创建为其所属接口的一个子页面。例如，BaseAudioContext/currentTime 被记录在 https://developer.mozilla.org/zh-CN/docs/Web/API/AudioContext/currentTime。