logo标签列表

Swift 2中的文档注释新格式是什么？（XCode 7 beta 3）

swiftdocumentationcommentsswift2xcode7
10

这里有一篇由Nate Cook和Mattt Thompson撰写的精彩文章，介绍了Swift文档注释的格式。

然而，自从Swift 2在XCode 7 beta中发布后，它的某些部分似乎不再起作用。例如:param:和:returns:不能产生期望的结果（它们只是按原样呈现）。

其他部分似乎仍然有效（即/// ...或/** ... */样式的两种类型的注释，代码块，列表），但是没有办法将文档标记为类似核心API的部分。

是否有人知道在Swift 2中如何突出显示方法参数和返回结果（以前:param:和:returns:完成的）的文档注释?

3个回答
10
如果你正在寻找“符号文档标记语法”，也就是想了解使用Markdown为你的方法编写文档的新语法（Xcode 7），那么你可以在苹果的网站上查看标记格式参考。
以下是如何定义一个“块注释”：
/**
  line of text with optional markup commands
  …
  line of text with optional markup commands
*/

这是一个带有最重要标签的评论示例：
/**
  Just testing documentation using Markdown
  - returns: Bool
  - parameter param1:String
  - parameter param2:String
  - Throws: error lists
*/

这是短格式。
/// line of text with optional markup commands
块参数的参数怎么样？ - Ky -
8
"

Xcode 7有什么新功能。 给出了一个提示

Markdown注释在Quick Help中显示为富文本，包含嵌入式图像和链接。

Xcode 7 beta版本的发布说明如下：

Swift文档注释使用基于Markdown格式的语法，使其与playgrounds中的富注释对齐。（20180161）

接着是一个简短的描述。

例如，

"
/**
    Repeats a string `times` times.

    :param: str     The string to repeat.
    :param: times   The number of times to repeat `str`.

    :returns: A new string with `str` repeated `times` times.
*/
func repeatString(str: String, times: Int) -> String {
    return join("", Array(count: times, repeatedValue: str))
}

从http://nshipster.com/swift-documentation/现在将被写成

/// Repeats a string `times` times.

/// - Parameters:
///     - str:     The string to repeat.
///     - times:   The number of times to repeat `str`.
/// - returns: A new string with `str` repeated `times` times.
func repeatString(str: String, times: Int) -> String {
   return Repeat(count: times, repeatedValue: str).joinWithSeparator("")
}

或者使用多行注释：
/**
    Repeats a string `times` times.

    - Parameter str:   The string to repeat.
    - Parameter times: The number of times to repeat `str`.
    - returns: A new string with `str` repeated `times` times. 
*/
func repeatString(str: String, times: Int) -> String {
    return Repeat(count: times, repeatedValue: str).joinWithSeparator("")
}

有关Markdown的更多信息，请参见 很多内容适用于内联文档注释，例如：

并且大部分

例如，您可以添加

     **重要：** `times` 不得为负数。

其中“重要”被呈现为强调。

非常好。非常感谢。 - 0x416e746f6e
4
在 Xcode 7 beta 4 中，参数列表只能这样书写：
 - parameter str:     The string to repeat.
 - parameter times:   The number of times to repeat `str`.

（这应该是对Martin R的评论，但我没有足够的声望去这样做。）

（这应该是对 Martin R 的帖子的评论，但我没有足够的声誉去发表评论。）
我一直在为什么:param:会渲染成":param:"而苦恼。 - Nicolas Miari
只要你添加了有价值的东西，就可以很好地扩展别人的答案。在我看来没问题。 :) - Dan Beaulieu
网页内容由stack overflow 提供, 点击上面的
可以查看英文原文，
原文链接