Xcode Swift Documentation Links with Anchors

So Apple started using Markdown for Swift documentation metadata in both Playground and source file comments. Cool.

If you want to know more, you should check out

One of the first things I noticed is that it’s not readily apparent how to create an in-documentation link to additional documentation that includes an anchor.Images, web links, etc. are all pretty well documented, but let’s take an example albeit a contrived one:

Here’s a Swift function that returns an Array of CGPoint structs

func arrayOfPoints (number: Int) -> [CGPoint] {
 ...
    return points
}

Here’s an example of Markdown syntax for documentation in the comments of the above function.

/// - parameter number: the number of CGPoint
///   elements in the returned array
/// - returns: Array of CGPoint
func arrayOfPoints (number: Int) -> [CGPoint] {
 ...
}

 

This results in the following in my copy of Xcode 7.1 when I option-click the function name

Xcode 7.1 Screen Grab

 

Now I said this is a contrived example and it will be, but lets assume that we want to create a link to the Xcode documentation for CGPoint even though there is one in the automatically generated function declaration documentation section.

The logical choice is to right-click on the hyperlink for CGPoint in the documentation and copy it…

xcdoc://?url=developer.apple.com/library/etc/redirect/xcode/ios/1151/documentation/GraphicsImaging/Reference/CGGeometry/index.html

…but that does not work as you would expect. That link takes you to the documentation but only to the file, not the CGPoint anchor within the file. Better than nothing, but definitely suboptimal. Just for reference, here’s the xcdoc url in the markdown documentation from before. I’ve replaced CGPoint in the returns section with URL syntax.

/// - parameter number: the number of CGPoint
///   elements in the returned array
/// - returns: Array of [CGPoint](xcdoc://?url=developer.apple.com/library/etc/redirect/xcode/ios/1151/documentation/GraphicsImaging/Reference/CGGeometry/index.html)
func arrayOfPoints (number: Int) -> [CGPoint] {
  ...
}

I started digging and found that a file:/// link to the local documentation including the anchor will work. Note that I swapped out the /Users/username for our friend ~

/// - parameter number: the number of CGPoint
///   elements in the returned array
/// - returns: Array of [CGPoint](file:///~/Library/Developer/Shared/Documentation/DocSets/com.apple.adc.documentation.iOS.docset/Contents/Resources/Documents/documentation/GraphicsImaging/Reference/CGGeometry/index.html#//apple_ref/c/tdef/CGPoint)
func arrayOfPoints (number: Int) -> [CGPoint] {
 ...
}

This results in a link to the CGGeometry documentation on the local docset and it opens directly to the anchor for CGPoint.

Is it worth this extra trouble to create links that will render your documentation extremely brittle? These have a code smell slightly worse than a Calcutta porta-potty. Probably not, but that’s not my call. I would like to see Apple fix their anchor links so they can be copied and pasted as described above.

Maybe if this shows up on Google it will save someone else some time.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>