Can't document - -= / /= operators

[leif-ibsen]

Description

I'm trying to use DocC to document a Swift big integer package 'BigInt'.

I'm using Xcode 15.2 (15C500b).

The package main structure is called 'BInt'. It implements among other things the overloaded operators

& &= | |= ^ ^= ~ + += - -= * *= / /= % %= ** == != < > <= >= << <<= >> >>=

The BInt extension file organizes the layout of the documentation and it works as expected
for all the operators, except for

- -= / /=

For - and -= Xcode suggests suffixes to resolve the overload ambiguity,
but later claims that the selected function does not exist.

For / and /= Xcode doesn't recognize / and /= as operators.

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

That the operators

- -= / /=

behave like the other operators with respect to documentation.

Actual behavior

Steps To Reproduce

No response

Swift-DocC Version Information

No response

Swift Compiler Version Information

swift-driver version: 1.87.3 Apple Swift version 5.9.2 (swiftlang-5.9.2.2.56 clang-1500.1.0.2.5)
Target: x86_64-apple-macosx14.0

[d-ronnqvist]

This issue has previously been reported in #714 and fixed in #717 and #739. Both those PRs have also been cherry-picked into the 5.10 release in #750 and #772.

Please check with the latest main or the 5.10 release to see if there are any other bugs with linking to operators still impacting that project and reopen this issue with more information if there are any.

[leif-ibsen]

I'm afraid I can't figure out how to download and install release 5.10.

I guess it will be in the next Xcode release, so I'll have to wait for that.

[d-ronnqvist]

You can download a 5.10 toolchain for Xcode from swift.org/download/. After you run the installer you can change toolchains from the Xcode > Toolchains menu.

This menu group is only visible when you have one or more custom toolchains installed.

[leif-ibsen]

I tried, and now it all seems to work. Thank you

[leif-ibsen]

Just one more question. When I use toolchain 5.10 in Xcode everything works,
but when I execute the command line command

swift package --disable-sandbox preview-documentation --taget BigInt

to build the documentation, the problem is still there,
so it seems that the old toolchain is used.

How can I force toolchain 5.10 to be used in this situation?

[d-ronnqvist]

Yes, the toolchain setting in Xcode only applies to Xcode. You can pass a --toolchain argument to the swift CLI to use a custom toolchain. For example:

swift package \
 --toolchain /Users/YOUR_USERNAME/Library/Developer/Toolchains/swift-5.10-DEVELOPMENT-SNAPSHOT-2024-01-18-a.xctoolchain \
 --disable-sandbox \
 preview-documentation \
 --target BigInt

[leif-ibsen]

It works, thank you.
It seems that the --disable-sandbox argument must come first, though.

[leif-ibsen]

Sorry to bother you again, but although everything looks fine when generating documentation in Xcode
with the 'Build Documentation' command, there are still problems when trying to publish to GitHub Pages.

I made a small test package DocCTest with the operators

- -= / /= % %= << <<= >> >>=

and tried to preview the documentation with the command

swift package --toolchain /Library/Developer/Toolchains/swift-5.10-DEVELOPMENT-SNAPSHOT-2024-01-25-a.xctoolchain
--disable-sandbox preview-documentation --target DocCTest --port 8082

and it gave me the following warnings

/Users/leifibsen/Documents/SwiftXcode/DocCTest/Sources/DocCTest/DocCTest.docc/Extensions/BIntExt.md:19:5: warning: Can't resolve '(::)-3woeb'
/Users/leifibsen/Documents/SwiftXcode/DocCTest/Sources/DocCTest/DocCTest.docc/Extensions/BIntExt.md:20:5: warning: Can't resolve '(::)-2wsf1'
/Users/leifibsen/Documents/SwiftXcode/DocCTest/Sources/DocCTest/DocCTest.docc/Extensions/BIntExt.md:21:5: warning: Can't resolve '=(::)'

but it was still possible to see all operators in the preview.

I then published to GitHub Pages with the command

swift package --toolchain /Library/Developer/Toolchains/swift-5.10-DEVELOPMENT-SNAPSHOT-2024-01-25-a.xctoolchain
--allow-writing-to-directory ./docs generate-documentation --target DocCTest
--disable-indexing --transform-for-static-hosting --hosting-base-path DocCTest --output-path ./docs

You can see the result at

https://leif-ibsen.github.io/DocCTest/documentation/docctest

Clicking one of the operators % %= << <<= >> >>= gives

The page you're looking for can't be found.

although it works in the preview.

I wonder what is wrong?

Best regards