Swift文档评论

我有几个关于Swift文档评论的问题。

  1. 无论如何，有一些相关的声明部分，像苹果的文档一样。 例如，当我select并单击tablewView（_：heightForRowAtIndexPath :)方法时，它将链接到生成的文档中的其他3个相关方法。

  2. 有没有快速的警告标签？ 我知道在Objective-C中它允许你做@warning，并在生成的文档中得到一个粗体的警告。 但是，警告：在快速的文档评论中没有做任何事情，所以我很好奇，如果有另一种方式。

  3. 有什么方法可以将文档制作成与Apple文档类似格式的HTML文件。 我知道在其他IDE的其他语言，如Eclipse，你可以生成代码的HTML文档。 XCode有这个吗？

编辑：迅速丰富的文档已经在Xcode 6.3 Beta 2（6D532l）大大改善 。

现在您可以使用Markdown来编写Playground和代码文档注释。

  • 对于丰富的Playground文档，请使用//:或/*: */
  • 对于代码文档使用///或/** */

示例注释 

 /// This function returns a *hello* string for a given `subject`. /// /// **Warning:** The returned string is not localized. /// /// Usage: /// /// println(hello("Markdown")) // Hello, Markdown! /// /// :param: subject The subject to be welcomed. /// /// :returns: A hello string to the `subject`. func hello(subject: String) -> String { return "Hello, \(subject)!" }

示例popover

广告。 1.否。“相关声明”function以某种方式从AppleDoc @see标签转换而来，但不能在Swift源文件中生成这些标签。

广告。 不，我不认为会有一个，因为斯威夫特的安全理想。 但是，您可以使用reST强调语法来生成粗体文本： 

 /// **Warning:** This method does something unsafe.

虽然目前还不支持文档popup，但在Swift标准库文档注释（ 最显着的是String ）中这样的语法非常常见，表明格式化function将在不久的将来被添加。

广告。 3.尽pipeXcode 可以生成文档注释的XML表示 ，但它不能生成HTML文件。 我知道的唯一工具就是这样，是爵士乐 。

只要知道更多的信息或添加了新的function，这个答案就会被更新。

参考：

  • NSHipster：Swift文档
  • 快速reStructuredText文档

Xcode 7.0 beta 4

记号已经改变（ :param:不再工作了…） 

 /// Creates the string representation of the poo with requested size. /// /// - warning: Be carefull! Poos can hurt. /// - parameter size: requested size of the poo /// - returns: string representation of the poo func makePoo(size: String) -> String { return "Ouch. This is \(size) poo!" }

它看起来像这样：

弹出与文档

您可以使用///或/** */

（3）为了在HTML中生成文档（甚至生成docset），我强烈build议为此目的而构build的爵士乐 。

即使它仍然是在制品，它工作得很好，并生成与苹果文档相似的文档

Interesting Posts