Linking to SwiftPM dependencies in DocC, in Xcode

Using Swift
1

I continue to run into issues making my docs nice. I’m trying to document this:

extension
Quantity
{
	/**
		See ``/RealModule/Double/isApproximatelyEqual(to:relativeTolerance:norm:)``
	*/
	
	func
	isApproximatelyEqual(to: Double)
		-> Bool
	{
		return self.asDouble.isApproximatelyEqual(to: to)
	}
	
	/**
		Returns the quantity’s value as an approximately equal ``/Swift/Double``, using the
		rules of ``/Swift/NSDecimalNumber/doubleValue``.
	*/
	
	var		asDouble				:	Double			{ self.value.asDouble }
}

But I get all sorts of warnings, depending on exactly how I structure the link above to isApproximatelyEqual(to:relativeTolerance:norm:). As shown above, it "Can't resolve 'RealModule'". Googling tells me --additional-symbol-graph-dir is needed, but I can’t do that in Xcode afaik.

Similarly, I can't link to NSDecimalNumber/doubleValue. I've tried prefixing it /Swift, /Foundation, and /Swift/Foundation, and in all cases, it just says "'NSDecimalNumber' doesn't exist at '/CalcNC/Swift'", which seems just plain wrong for a link path that starts with a /.

2

Unfortunately, that's a limitation for DocC and referencing external DocC archives - while Apple arranges links for this sort of thing for their Framework documentation, the DocC tooling doesn't have support to reference external DocC archives beyond some initial experimental work that appeared in Swift 6.2 (and for all practical purposes, it's not available)

The best workaround here is instead of trying to assemble a link to the symbol name, use a direct HTML link to the developer documentation - so rather than:

`/RealModule/Double/isApproximatelyEqual(to:relativeTolerance:norm:)``

Try using:

[isApproximatelyEqual(to:relativeTolerance:norm:)](https://swiftpackageindex.com/apple/swift-numerics/documentation/realmodule/swift/numeric/isapproximatelyequal(to:relativetolerance:norm:))

Note: I stripped out the version from the URL that I dug up through Swift Package Index:
https://swiftpackageindex.com/apple/swift-numerics/1.1.1/documentation/realmodule/swift/numeric/isapproximatelyequal(to:relativetolerance:norm:), which makes this a little "less pinned" to that specific version, as the modified link resolves to "the latest version", which is handy in a docs reference unless you mean to specifically pin it to a version.

2 Likes