ad121 ad121 - 3 months ago 11
Swift Question

Swift Documentation Comments

I have a few questions about Swift documentation comments.


  1. Is there anyway 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 3 other related methods within the generated documentation.

  2. Is there any warning tag in swift? I know in objective-c it allowed you to do @warning and get a bolded warning in the documentation that is generated. However, :warning: does nothing in swift documentation comments, so I was curious if there was another way.

  3. Is there any way to make your documentation into an HTML file that is a similar format as the Apple Documentation. I know in other IDEs for other languages, such as Eclipse, you can just generate html documentation for your code. Does XCode have this?


Answer

Edit: Swift rich documentation has been greately improved in Xcode 6.3 Beta 2 (6D532l).

Now you can use Markdown to write both Playground and code documentation comments.

  • For rich Playground documentation use //: or /*: */
  • For code documentation use /// or /** */

Example comment

/// 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)!"
}

Example popover


Ad. 1. No. The "related declarations" functionality is somehow coverted from AppleDoc @see tags, but it is not possible to produce those tags in Swift source files.

Ad. 2. No, and I don't think there will ever be one, because of Swift's ideals of safety. You can, however, use reST strong emphasis syntax to produce a bold text:

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

Although it is not yet supported in documentation popovers, syntax like this is very common in Swift Standard Library documentation comments (most notably for String), indicating that formatting functionality will be added in the near future.

Ad. 3. Altough Xcode can generate XML representation of the documentation comments, it cannot produce a HTML file. The only tool I know is capable of this, is jazzy.

This answer will be updated as soon as more information is known or new functionalities added.

Reference: