如何使用Swift文档注释 [英] How to use Swift documentation comments
问题描述
我对Swift文档的评论有一些疑问:
I have a few questions about Swift documentation comments:
-
有没有办法像某些Apple文档一样制作相关声明"部分?例如，当我 Option + 点击
tablewView(_:heightForRowAtIndexPath:)方法时，它会将我链接到生成的文档中的其他三个相关方法.
Is there a way to make a Related declarations section like some of the Apple documentation has? For example, when I Option+Click the
tablewView(_:heightForRowAtIndexPath:)method, it links me to three other related methods within the generated documentation.
Swift中是否有任何警告标记?我知道Objective-C允许我执行@warning并在生成的文档中得到加粗的警告.但是，:warning:在Swift的文档注释中什么也不做，所以我很好奇是否还有另一种方法.
Is there any warning tag in Swift? I know Objective-C allowed me to do @warning and get a bolded warning in the generated documentation. However, :warning: does nothing in Swift's documentation comments, so I was curious if there was another way.
是否可以将我的文档制作成与Apple文档类似格式的HTML文件?我知道在其他IDE(例如Eclipse)中，我可以为代码生成HTML文档. XCode有这个吗?
Is there a way to make my documentation into an HTML file that is a similar format as the Apple Documentation? I know in other IDEs, such as Eclipse, I can generate HTML documentation for my code. Does XCode have this?
推荐答案
该答案最后一次针对Swift 5.2和Xcode 11.4进行了修订.
您可以使用标记来编写标准代码文档(使用///或/** */)和丰富的游乐场文档(使用//:或/*: */).
You can use markup to write standard code documentation (using /// or /** */) and rich playground documentation (using //: or /*: */).
/// This function returns a welcoming string for a given `subject`.
///
/// ```
/// print(hello("World")) // Hello, World!
/// ```
///
/// - Warning: The returned string is not localized.
/// - Parameter subject: The subject to be welcomed.
/// - Returns: A hello string to the `subject`.
func hello(_ subject: String) -> String {
return "Hello, \(subject)!"
}
关于记录相关符号，存在一个SeeAlso标记标签，但要求您在相关符号的文档页面上写一个明确的URL.
As for documenting related symbols, there is a SeeAlso markup tag but requires you to write an explicit URL to your related symbol's documentation page.
如果要为您的项目生成HTML文档索引，建议您检出 jazzy 和 swift-doc .它们都是令人惊叹的开源项目，甚至被Apple本身使用.
If you want to generate HTML documentation index for your project, I recommend checking out jazzy and swift-doc. They're both amazing open-source projects, and are even used by Apple itself.
这篇关于如何使用Swift文档注释的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！
