What Is the Markup Format for Documentation on the Parameters of a Block in Swift

What is the markup format for documentation on the parameters of a block in Swift?

You have to give a name to the parameter, but precede it with an underscore:

/**
 Foo

 - parameter completion: A block to execute
 - parameter aflag: Some Bool flag
 */
func foo(completion: (_ aflag: Bool) -> Void) {
    // do something
}

How do you document the parameters of a function's closure parameter in Swift 3?

As far as I know, you can only document the closure parameters if you label them:

/// Calls bar with "Hello, world"
/// - parameter bar: A closure to call
/// - parameter theString: A string to use
func foo(bar: (theString: String) -> Void) {
    bar(theString: "Hello, world")
}

This is less than ideal: it forces you to use an argument label when you call the closure, and if there are naming conflicts, there seems no way to distinguish between the two.

Edit: As @Arnaud pointed out, you can use _ to prevent having to use the parameter label when calling the closure:

/// Calls bar with "Hello, world"
/// - parameter bar: A closure to call
/// - parameter theString: A string to use
func foo(bar: (_ theString: String) -> Void) {
    bar("Hello, world")
}

In fact, this is the only valid approach in Swift 3 because parameter labels are no longer part of the type system (see SE-0111).

What is the new format of documentation comments in Swift 2? (XCode 7 beta 3)

If you're looking for Symbol Documentation Markup Syntax, meaning if you want to know the new syntax (Xcode 7) to write documentation for your methods using Markdown, there is the Markup Formatting Reference on Apple's website.

Here's how you define a Block Comment :

/**
  line of text with optional markup commands
  …
  line of text with optional markup commands
*/ 

And here's an example of a comment with the most important tags :

/**
  Just testing documentation using Markdown
  - returns: Bool
  - parameter param1:String
  - parameter param2:String
  - Throws: error lists
*/

And here's the short format

/// line of text with optional markup commands

Xcode - Add Custom Documentation for Swift Closure

Reference:

• For reference see Markup Formatting Reference namely the section "Formatting Quick Help"

Workaround:

If those tags are not supported for the given location the only possible workaround seems to be right now:

struct S1 {
    
    /// description
    ///
    /// __returns__
    /// blah blah
    ///
    /// __parameters__
    /// blah blah
    var completion : (String, Int) -> (Bool)
}

How can I properly document a method with a completion handler in iOS swift

/**
Sends an API request to 4sq for venues around a given location with an optional text search

:param: location    A CLLocation for the user's current location
:param: query       An optional search query
:param: completion  A closure which is called with venues, an array of FoursquareVenue objects

:returns: No return value
*/
func requestVenues(location: CLLocation, query: String?, completion: (venues: [FoursquareVenue]?) -> Void) { … }

taken from https://thatthinginswift.com/documentation-and-quick-help/

How to add lists in Xcode documentation markup?

This actually has nothing to do with lists, but headings. Notice that if you remove the heading # Examples:, or just the # character, the markdown is rendered as expected.

For some reason, Xcode ignores all the text after it encounters a heading of any kind in a documentation comment.

See this example from this very old answer. It apparently worked back then!

/// Text like this appears in "Description".
///
/// Leave a blank line to separate further text into paragraphs.
///
/// You can use bulleted lists (use `-`, `+` or `*`):
///
/// - Text can be _emphasised_
/// - Or **strong**
///
/// Or numbered lists:
///
/// 7. The numbers you use make no difference
/// 0. The list will still be ordered, starting from 1
/// 5. But be sensible and just use 1, 2, 3 etc…
///
/// ---
///
/// More Stuff
/// ==========
///
/// Code
/// ----
///
/// Use backticks for inline `code()`. Indentations of 4 spaces or more will create a code block, handy for example usage:
///
///     // Create an integer, and do nothing with it
///     let myInt = 42
///     doNothing(myInt)
///
///     // Also notice that code blocks scroll horizontally instead of wrapping.
///
/// Links & Images
/// --------------
///
/// Include [links](https://en.wikipedia.org/wiki/Hyperlink), and even images:
///
/// ![Swift Logo](/Users/Stuart/Downloads/swift.png "The logo for the Swift programming language")
///
/// - note: That "Note:" is written in bold.
/// - requires: A basic understanding of Markdown.
/// - seealso: `Error`, for a description of the errors that can be thrown.
///
/// - parameters:
///   - int: A pointless `Int` parameter.
///   - bool: This `Bool` isn't used, but its default value is `false` anyway…
/// - throws: A `BadLuck` error, if you're unlucky.
/// - returns: Nothing useful.
public func doNothing(int: Int, bool: Bool = false) throws -> String {
    return "Totally contrived."
}

Xcode's "discussion" part stops before the first heading,

(Try deleting the headings and see what happens!)

The parameters and returns seem to be rendered fine though.

On the other hand, if I use a documentation generator like jazzy like the linked answer suggests, the headings and all the other text are rendered properly:

There is no Swift Logo because I didn't download one to my local machine :) Your documentation for formattedString function is also generated properly by jazzy, without needing to change anything.

As another alternative, AppCode generates documentation for both your formattedString function and the above example correctly too.

So I think this is a just a quirk/bug in Xcode. Documentation generators can still properly generate documentations from these comments.

---

Related Topics