Swift是否有文档生成支持？降价

问题描述 投票：224回答：11

许多语言都支持文档注释，允许生成器（如javadoc或doxygen）通过解析相同的代码来生成代码文档。

Swift有这样的类型文档评论功能吗？

swift documentation-generation
11个回答
368
投票

Xcode本身支持文档注释，在快速帮助中生成智能渲染文档（在⌥单击符号时在弹出框中，以及在快速帮助检查器⌥⌘2中）。

符号文档注释现在基于丰富的游乐场注释所使用的相同Markdown syntax，因此您在游乐场中可以执行的许多操作现在可以直接在源代码文档中使用。

有关语法的完整详细信息，请参阅Markup Formatting Reference。请注意，丰富的游乐场评论和符号文档的语法之间存在一些差异;这些都在文件中指出（例如，块引号只能在游乐场中使用）。

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

Updates

Xcode 7 beta 4~添加了“- Throws: ...”作为顶级列表项，与快速帮助中的参数和返回描述一起显示。

Xcode 7 beta 1~使用Swift 2对语法进行了一些重大更改 - 文档注释现在基于Markdown（与游乐场相同）。

Xcode 6.3（6D570）〜缩进文本现在被格式化为代码块，后续缩进被嵌套。似乎不可能在这样的代码块中留下空白行 - 尝试这样做会导致文本被添加到最后一行的末尾，其中包含任何字符。

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

Example for 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."
}

Syntax for Swift 2 (based on Markdown)

如何风格

///（内联）和/** */（块）样式注释都支持生成文档注释。虽然我个人更喜欢/** */评论的视觉风格，但Xcode的自动缩进可能会在复制/粘贴时破坏此评论样式的格式，因为它会删除前导空格。例如：

/**
See sample usage:

    let x = method(blah)
*/

粘贴时，代码块缩进将被删除，并且不再呈现为代码：

/**
See sample usage:

let x = method(blah)
*/

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

块元素

标题：

/// # My Heading

要么

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

副标题：

/// ## My Subheading

要么

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

横向规则：

/// ---

无序（项目符号）列表：

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

你也可以使用+或*作为无序列表，它必须是一致的。

有序（编号）列表：

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

代码块：

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

需要至少四个空格的缩进。

内联元素

重点（斜体）：

/// 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还会识别其他标记关键字，以便在“快速帮助”中突出显示。这些标记关键字大多采用- <keyword>:格式（例外是parameter，其中还包括冒号前的参数名称），其中关键字本身可以使用大写/小写字符的任意组合编写。

Symbol Section keywords

以下关键字在帮助查看器中显示为“描述”部分下方和“已申报”部分上方的突出部分。包含时，即使您可以在评论中以任何顺序包含它们，它们的顺序也会如下所示固定。

请参阅完整记录的部分关键字列表及其在Symbol Section Commands section of the Markup Formatting Reference中的预期用途。

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

或者，您可以这样编写每个参数：

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

Symbol Description Field keywords

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

Erica Sadun从this excellent blog article转发的完整名单。另请参阅完整记录的关键字列表及其在Symbol Description Field Commands section of the Markup Formatting Reference中的预期用途。

职责：

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

可用性：

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

告诫：

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

发展状况：

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

实施质量：

/// - complexity:

功能语义：

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

交叉参考：

/// - seealso:

 Exporting Documentation

HTML文档（旨在模仿Apple自己的文档）可以使用Jazzy（一个开源命令行实用程序）从内联文档生成。

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

控制台示例取自this NSHipster article

-1
投票

也许关注AppleDoc或Apple自己的HeaderDoc是一个好主意，这是不被认可的。我仍然可以在10.9 Mavericks终端中找到一些HeaderDoc提示（headerdoc2html）

我建议阅读最新的“What's New In Xcode”*（不确定它是否还在NDA下）*链接指向Xcode 5.1版本，其中包含有关HeaderDoc的信息。

-1
投票

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

Source

58
投票

以下是一些用于记录Xcode 6中的swift代码的东西。它对冒号非常错误和敏感，但它总比没有好：

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";
    }
}

如上所述，您可以使用格式化数字列表，项目符号，参数和返回值文档在快速帮助中呈现上述内容。

这些都没有记录 - 提交雷达来帮助他们。

37
投票

Xcode 8中的新功能，您可以选择这样的方法

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

然后按command + option + /或从Xcode的“编辑器”菜单中选择“结构” - “添加文档”，它将为您生成以下注释模板：

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

Swift包含“///”注释处理（尽管可能还不是所有内容）。

写下类似的东西：

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

}

然后选择 - 点击功能名称和voilà:)

11
投票

我可以确认ShakenManChild提供了peopr解决方案

请确保您在说明下面有一个空行！

8
投票

是。基础常见（我用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#>.
*/
7
投票

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

https://github.com/realm/jazzy

6
投票

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

5
投票

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

enter image description here

最新问题
© www.soinside.com 2019 - 2024. All rights reserved.