Link to operator functions in DocC

Development Swift-DocC
1

I have a package that defines addition operator functions as shown below. The function definitions are similar but the types are different.

public func + (lhs: Float, rhs: Vector<Float>) -> Vector<Float> {
    let result = vDSP.add(lhs, rhs.values)
    return Vector(result)
}

public func + (lhs: Double, rhs: Vector<Double>) -> Vector<Double> {
    let result = vDSP.add(lhs, rhs.values)
    return Vector(result)
}

I tried to link to these functions in a DocC file using the following:

### Addition Operators

- ``+(lhs:rhs:)``
- ``+(lhs:rhs:)``

But Xcode complains that the functions don't exist when I build the documentation. How can I define the types in each function link so Xcode knows which function I'm referring to?

2 Likes
2

does +(_:_:) work?

3

Here's how to modify your code:

`### Addition Operators

  • +(lhs: Float, rhs: Vector<Float>)
  • ``+(lhs: Double, rhs: Vector)```

In this example, the types are included within the function link itself. By separating the left-hand side (lhs) and right-hand side (rhs) arguments with a colon (:), you can specify their respective types. This way, DocC can differentiate between the two functions based on their unique type signatures.

4

Using just underscores doesn't work because the function is ambiguous.

- ``+(_:_:)``
5

I also tried all of the following but none of them work.

- ``+(Float, Vector<Float>)``
- ``+(lhs:Float,rhs:Vector<Float>)``
- ``+(lhs: Float, rhs: Vector<Float>)``
- ``+ (lhs: Float, rhs: Vector<Float>) -> Vector<Float>``
6

This DocC page mentions a unique identifier for identical symbols. But where do I find this unique identifier for the function? The referenced page also mentions using a suffix such as -func.op for operators but I don't understand how to apply it.

7

In a usual case (with methods and functions that aren't operators), Xcode should automatically insert a hash in the symbol link, like ``+(lhs:rhs:)-8x7v0``, but it looks like the auto-complete mechanism isn't working here for + operator functions. This is a bug; those should be inserted automatically if you're using Xcode's auto-complete (EDIT: which should be noted is distinct from Swift-DocC), or suggested if not (which it also looks here like it's not). Can you file an issue on Swift-DocC so we can take a look? The code snippet you have in your first post should be enough to work with.

/cc @ronnqvist

8

If I'm having trouble finding disambiguating hashes, I usually look in the build output's myProject.doccarchive/data/documentation/ directory for JSON files whose names correspond to the relevant symbols.

1 Like
9

If you copy and paste as many of the same signature for overloads, operator or not, then attempt to build, you can press the Fix-Its. This has been my method; it is functional but slow.

10

If I use the following

- ``+(_:_:)``

and then build the documentation, Xcode will complain about ambiguous functions as shown below.

Screenshot 2024-05-30 at 8.02.52 PM
Screenshot 2024-05-30 at 8.02.52 PM1092×198 20.2 KB

However, I can select the warning and choose a fix. This only works with +(_:_:), none of the other ways I mentioned earlier will provide the options to fix the link.

Screenshot 2024-05-30 at 8.03.26 PM
Screenshot 2024-05-30 at 8.03.26 PM974×1046 148 KB

This does provide a solution to my problem but it's definitely not ideal. It seems like Xcode should be able to suggest the list of fixes before I have to build the documentation.

3 Likes
11

What version of Xcode is this? Have you tried this with the upcoming 6.0 release? You can get it by downloading a recent "Swift 6 Development" toolchain.

Some fixes for linking to subtraction operators (-(_:_:) or -=(_:_:)) and linking to division operators (/(_:_:) or /=(_:_:)) should already be in the 5.10 release but there are a few other refinements and bug fixes in the 6.0 as well.

If there aren't any warnings with suggested fixes with the 6.0 release, please file an issue on Swift-DocC so that we can investigate further.

If there are warnings with suggested fixes but Xcode doesn't insert the expected disambiguation when autocompleting links, please report a Feedback on Xcode since that behavior is out of scope for the open source Swift-DocC project.

12

I already created an issue about this on the swift-docc repository. I'm using Xcode 15.4 and Swift 5.10 and have not tried anything on Swift 6 since it's still in development.

13

I don't know where this is coming from but practically nothing of this is correct.

2 Likes
14

Ah! I see it now. That issue happens because Xcode doesn't autocomplete the operator name correctly and with all parameter labels different DocC treats it as "significantly" different from any of the known names at that scope.

This Xcode issue—which is already known—is out of scope for tacking as an issue in the Swift-DocC repo.