我在Xcode二进制文件中发现了一些有趣的东西。以.swiftdoc结尾的文件。 它肯定有文档，因为这些文件包含Swift UIKit / Foundation API的文档，不幸的是，它似乎是一种专有的文件格式，用于Xcode中的文档查看器。

Swift包含了"///"注释处理(尽管可能还不是全部)。

可以这样写:

/// Hey!
func bof(a: Int) {

}

然后选项-点击func名称和voilà:)

也许关注一下AppleDoc或苹果自己的HeaderDoc是个好主意，它不太被认可。 我仍然可以在10.9 Mavericks终端中找到一些HeaderDoc提示(headerdoc2html)

我推荐阅读最新的“Xcode的新功能”*(不确定它是否仍处于保密协议之下) *链接指向Xcode 5.1版本，其中也包含有关HeaderDoc的信息。

从Xcode 5.0开始，支持Doxygen和HeaderDoc结构化注释。

源

下面是一些在Xcode 6中用于记录swift代码的东西。它有很多bug，对冒号很敏感，但总比没有强:

class Foo {

    /// This method does things.
    /// Here are the steps you should follow to use this method
    ///
    /// 1. Prepare your thing
    /// 2. Tell all your friends about the thing.
    /// 3. Call this method to do the thing.
    ///
    /// Here are some bullet points to remember
    ///
    /// * Do it right
    /// * Do it now
    /// * Don't run with scissors (unless it's tuesday)
    ///
    /// :param: name The name of the thing you want to do
    /// :returns: a message telling you we did the thing
    func doThing(name : String) -> String {
        return "Did the \(name) thing";
    }
}

上述内容在快速帮助中呈现，正如您所期望的格式化数字列表、项目符号、参数和返回值文档一样。

所有这些都没有被记录下来-档案雷达来帮助他们前进。

我可以确认ShakenManChild已经为人们提供了解决方案

只要确保在描述下面有一个空行!

在Xcode中原生支持文档注释，在快速帮助中生成智能呈现的文档(无论是在弹出窗口中，当单击符号时，还是在快速帮助检查器中⌘2)。

符号文档注释现在基于富游乐场注释使用的相同Markdown语法，因此您在游乐场中可以做的许多事情现在可以直接在源代码文档中使用。

有关语法的详细信息，请参阅标记格式参考。注意，在丰富的游乐场注释和符号文档之间有一些语法差异;这些都在文件中指出了(例如，方块引号只能在操场上使用)。

下面是一个示例和当前适用于符号文档注释的语法元素列表。

---

更新

Xcode 7 beta 4 ~增加了“- Throws:…”作为顶级列表项，在快速帮助中与参数和返回描述一起出现。

Xcode 7 beta 1 ~ Swift 2在语法上有一些重大变化——现在基于Markdown的文档注释(和操场一样)。

Xcode 6.3 (6D570) ~缩进的文本现在被格式化为代码块，后续的缩进被嵌套。在这样的代码块中留下空行似乎是不可能的——试图这样做会导致文本被附加到最后一行的末尾，其中包含任何字符。

Xcode 6.3 beta版~现在可以使用反勾号将内联代码添加到文档注释中。

---

Swift 2示例

/// Text like this appears in "Description".
///
/// Leave a blank line to separate further text into paragraphs.
///
/// You can use bulleted lists (use `-`, `+` or `*`):
///
/// - Text can be _emphasised_
/// - Or **strong**
///
/// Or numbered lists:
///
/// 7. The numbers you use make no difference
/// 0. The list will still be ordered, starting from 1
/// 5. But be sensible and just use 1, 2, 3 etc…
///
/// ---
///
/// More Stuff
/// ==========
///
/// Code
/// ----
///
/// Use backticks for inline `code()`. Indentations of 4 spaces or more will create a code block, handy for example usage:
///
///     // Create an integer, and do nothing with it
///     let myInt = 42
///     doNothing(myInt)
///
///     // Also notice that code blocks scroll horizontally instead of wrapping.
///
/// Links & Images
/// --------------
///
/// Include [links](https://en.wikipedia.org/wiki/Hyperlink), and even images:
///
/// ![Swift Logo](/Users/Stuart/Downloads/swift.png "The logo for the Swift programming language")
///
/// - note: That "Note:" is written in bold.
/// - requires: A basic understanding of Markdown.
/// - seealso: `Error`, for a description of the errors that can be thrown.
///
/// - parameters:
///   - int: A pointless `Int` parameter.
///   - bool: This `Bool` isn't used, but its default value is `false` anyway…
/// - throws: A `BadLuck` error, if you're unlucky.
/// - returns: Nothing useful.
func doNothing(int: Int, bool: Bool = false) throws -> String {
    if unlucky { throw Error.BadLuck }
    return "Totally contrived."
}

---

Swift 2的语法(基于Markdown)

评论风格

支持///(内联)和/** */(块)样式的注释来生成文档注释。虽然我个人更喜欢/** */ comments的视觉风格，但Xcode的自动缩进会在复制/粘贴时破坏这种注释风格的格式，因为它会删除前导空格。例如:

/**
See sample usage:

    let x = method(blah)
*/

粘贴时，代码块缩进被移除，它不再被呈现为代码:

/**
See sample usage:

let x = method(blah)
*/

出于这个原因，我通常使用///，并将在这个答案中的其余示例中使用它。

块元素

标题:

/// # My Heading

or

/// My Heading
/// ==========

副标题:

/// ## My Subheading

or

/// My Subheading
/// -------------

横向规则:

/// ---

无序(项目符号)列表:

/// - An item
/// - Another item

你也可以对无序列表使用+或*，只要保持一致即可。

有序(编号)列表:

/// 1. Item 1
/// 2. Item 2
/// 3. Item 3

代码块:

///    for item in array {
///        print(item)
///    }

至少需要缩进4个空格。

行内元素

重点(斜体):

/// Add like *this*, or like _this_.

强(粗体显示):

/// You can **really** make text __strong__.

注意，不能在同一个元素上混合使用星号(*)和下划线(_)。

内联代码:

/// Call `exampleMethod(_:)` to demonstrate inline code.

链接:

/// [Link Text](https://en.wikipedia.org/wiki/Hyperlink)

图片:

/// ![Alt Text](http://www.example.com/alt-image.jpg)

URL可以是web URL(使用“http://”)，也可以是绝对文件路径URL(我似乎无法获得相对文件路径)。

链接和图像的url也可以从内联元素中分离出来，以便将所有url保存在一个易于管理的位置:

/// A [link][1] an an ![image][2]
///
/// ...
///
/// [1]: http://www.example.com
/// [2]: http://www.example.com/image.jpg

关键字

除了Markdown格式，Xcode还识别其他标记关键字，以便在快速帮助中显著显示。这些标记关键字大多采用格式- <关键字>:(例外是parameter，它还包括冒号之前的参数名)，其中关键字本身可以用大写/小写字符的任何组合来编写。

关键字

以下关键字在帮助查看器中显示为突出的部分，位于“描述”部分的下方和“声明中的”部分的上方。当包含它们时，它们的顺序是固定的，如下所示，即使你可以在评论中以任何你喜欢的顺序包含它们。

请参阅“标记格式化参考”的“符号节命令”部分中的完整文档化的节关键字列表及其预期用途。

/// - parameters:
///   - <#parameter name#>:
///   - <#parameter name#>:
/// - throws:
/// - returns:

或者，你可以这样写每个参数:

/// - parameter <#parameter name#>:

符号说明字段关键字

以下关键字列表在帮助查看器的“描述”部分的主体中以粗体标题显示。它们将以您编写它们的任何顺序出现，就像“Description”部分的其余部分一样。

完整的列表转述自Erica Sadun这篇优秀的博客文章。另请参阅标记格式参考的符号描述字段命令部分中的完整文档化的关键字列表及其预期用途。

归因:

/// - author:
/// - authors:
/// - copyright:
/// - date:

可用性:

/// - since:
/// - version:

警告:

/// - attention:
/// - important:
/// - note:
/// - remark:
/// - warning:

发展状态:

/// - bug:
/// - todo:
/// - experiment:

实现品质:

/// - complexity:

功能语义:

/// - precondition:
/// - postcondition:
/// - requires:
/// - invariant:

交叉参考:

/// - seealso:

---

输出文档

HTML文档(旨在模仿苹果自己的文档)可以使用Jazzy(一个开源命令行实用程序)从内联文档中生成。

$ [sudo] gem install jazzy
$ jazzy
Running xcodebuild
Parsing ...
building site
jam out ♪♫ to your fresh new docs in `docs`

控制台示例取自这篇NSHipster文章

如果你只使用Swift，那么Jazzy值得一看。

https://github.com/realm/jazzy

是的。基本公共(我用Obj-C等效为它制作了片段)

objective - c:

/**
 @brief <#Short description - what it is doing#>

 @discussion <#Description#>

 @param  <#paramName#> <#Description#>.

 @return <#dataType#> <#Description#>.
 */

斯威夫特

/**
<#Short inline description - what it is doing#>

<#Description#>

:param:  <#paramName#> <#Description#>.

:returns: <#dataType#> <#Description#>.
*/

在Xcode 8中，你可以这样选择一个方法

func foo(bar: Int) -> String { ... }

然后按command + option + /或在Xcode的“编辑器”菜单中选择“结构”-“添加文档”，它会为你生成如下注释模板:

/// <#Description#>
///
/// - parameter bar: <#bar description#>
///
/// - returns: <#return value description#>

在Xcode编辑器->结构->添加文档。

Jazzy可以帮助生成漂亮的苹果风格的文档。 下面是一个示例应用程序，详细介绍了如何快速使用和配置。

https://github.com/SumitKr88/SwiftDocumentationUsingJazzy