title: Swift Markup: Callback argument breaks documentation string
body: <p>I am using <a href="https://developer.apple.com/library/content/documentation/Xcode/Reference/xcode_markup_formatting_ref/index.html" rel="nofollow noreferrer">Swift Markup Language</a> to document class methods. Everything goes OK, but, here is a subtle issue. </p>
  
  <p>Below goes a list of examples to explain what I am asking about.</p>
  
  <hr>
  
  <p><strong>1) Everything looks fine</strong></p>
  
  <pre><code>/// My Fancy Method.
  ///
  /// - Parameter number: A number.
  /// - Parameter flag: A flag.
  func methodWithoutCallback(integer number: Int, boolean flag: Bool) {
  
  }
  </code></pre>
  
  <p><a href="https://i.stack.imgur.com/hQyck.png" rel="nofollow noreferrer"><img src="https://i.stack.imgur.com/hQyck.png" alt="enter image description here"></a></p>
  
  <p><strong>2) Still doing well</strong></p>
  
  <pre><code>/// A method with callback (no arguments).
  ///
  /// - Parameter string: A string.
  /// - Parameter callback: A callback without arguments.
  func methodWithVoidCallback(string name: String, _ callback: () -&gt; ()) {
  
  }
  </code></pre>
  
  <p><a href="https://i.stack.imgur.com/NfmHa.png" rel="nofollow noreferrer"><img src="https://i.stack.imgur.com/NfmHa.png" alt="enter image description here"></a></p>
  
  <p><strong>3) Not exactly what I've expected</strong></p>
  
  <pre><code>/// This time things go wrong...
  ///
  /// - Parameter number: A number.
  /// - Parameter callback: Why there is a box with "No description" below?
  func methodWithIntCallback(floating number: Float, _ callback: (Int) -&gt; ()) {
  
  }
  </code></pre>
  
  <p><a href="https://i.stack.imgur.com/1zQw7.png" rel="nofollow noreferrer"><img src="https://i.stack.imgur.com/1zQw7.png" alt="enter image description here"></a></p>
  
  <p><strong>4) Using typealias removes that thing away</strong></p>
  
  <pre><code>typealias Callback = (Int) -&gt; ()
  /// And, there is a way to repair, but need typealias
  ///
  /// - Parameter number: A number.
  /// - Parameter callback: A callback (no box below)
  func methodWithTypealiasedIntCallback(floating number: Float, _ callback: Callback) {
  
  }
  </code></pre>
  
  <p><a href="https://i.stack.imgur.com/aoYc8.png" rel="nofollow noreferrer"><img src="https://i.stack.imgur.com/aoYc8.png" alt="enter image description here"></a></p>
  
  <hr>
  
  <p>Did anybody have this issue? Or is it a kind of expected behavior? The issue comes up while using <strong>Xcode 9.2 (9C40b)</strong> and <strong>Swift 4</strong> (if it matters). </p>
  
  <hr>
  
  <blockquote>
    <p><strong>UPDATE</strong>: Seems to be a duplicate of <a href="https://stackoverflow.com/questions/38669725">this question</a>. But I wanted to clarify then: there is no way to ignore that box altogether, right? Because here is what you're getting if using proposed approach:</p>
  </blockquote>
  
  <pre><code>/// So, the box is coming up.
  func methodWithCallbackParameterAnnotated(_ callback: (_ value: Int) -&gt; Int) {
  
  }
  </code></pre>
  
  <p><a href="https://i.stack.imgur.com/vkdwD.png" rel="nofollow noreferrer"><img src="https://i.stack.imgur.com/vkdwD.png" alt="enter image description here"></a></p>