Swift Documentation Comments

问题

I have a few questions about Swift documentation comments.

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.
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.
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?

回答1:

You can use markup to write both playground and code documentation comments.

For rich playground documentation use //: or /*: */
For code documentation use /// or /** */

Example

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

Answers to your questions

Ad. 1. No. While there is a SeeAlso markup tag, it's not yet clever enough to link to related symbols inside your or third-party library.

Ad. 2. Yes, there is a Warning markup tag. See my above example.

Ad. 3. Altough Xcode can generate XML representation of the documentation comments, it cannot produce a HTML file. I recommend using jazzy for that.

回答2:

Xcode 7.0 beta 4

The notation has been changed (:param: does not work anymore ...)

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

And it looks like this:

You can use either /// or /** */

回答3:

(3) To generate your documentation in HTML (or even generate docsets), I strongly recommend jazzy which was built for that purpose.

Even if it's still WIP, it works really well and generate documentation with similar presentation to the Apple documentation

回答4:

Use the following notation for documentation comments.

/**
 This method sum two double numbers and returns.

 - parameter number1: First Double Number.
 - parameter number2: Second Double Number.
 - returns: The sum of two double numbers.

 # Notes: #
 1. Parameters must be **double** type
 2. Handle return type because it is optional.

 # Example #
```
 if let sum = self.add(number1: 23, number2: 34) {
  print(sum)
 }
 ```
*/


func add(number1: Double, number2: Double) -> Double? {
    return number1 + number2
}

来源：https://stackoverflow.com/questions/27715933/swift-documentation-comments

标签

ios

xcode

swift

xcode6

documentation-generation