How do you generate the method overload hash in Jazzy?

According to the docs, Jazzy supports Apple's DocC-style symbol links:

Jazzy understands Apple's DocC-style links too, for example:

MyClass/method(param1:) - a link to the documentation for that method that appears as just method(param1:) in the rendered page.
<doc:method(_:)-e873> - a link to a specific overload of method(_:). Jazzy can't tell which overload you intend and links to the first one.

That said, how does one obtain the -e873 hash in the example above?

Generating the hashes out of a module's symbol graph is open source. You can dig into swift-docc and read the code that parses the symbol graph and generates the URLs for overloaded symbols. SymbolReference has a bunch of initializers that generate the correct path depending on whether the symbol is a name or kind overload: swift-docc/SymbolReference.swift at main · apple/swift-docc · GitHub

2 Likes

Sorry, I think there may have been some confusion. I'm not a maintainer of Jazzy, I'm simply trying to write some docs for our existing code base, which uses Jazzy. Is there really no tool to get these overload hashes?

You are asking about generating the hashes so I think my confusion is understandable. If you simply need a link to a given overloaded symbol — Xcode's link autocompletion while writing documentation should be sufficient. If you haven't tried adding links in documentation have a look at the DocC WWDC videos, for example https://developer-mdn.apple.com/videos/play/wwdc2021/10166 at around the 17min mark and onwards.

1 Like

Right, therein lies the problem, because our entire development team is Linux-based! That's part of why we're using Jazzy. Is it possible to get this working in VSCode?

I could be misunderstanding- but if you're using Jazzy and don't intend to migrate to DocC I don't think you'll have any use for the overload hashes.

The overload hashes are used by DocC to know which specific overload of a symbol to link to.

From the Jazzy readme (emphasis mine):

<doc:method(_:)-e873> - a link to a specific overload of method(_:). Jazzy can't tell which overload you intend and links to the first one.

If your primary documentation tool is Jazzy, you can likely stick with the default Jazzy link syntax:

Jazzy can also generate cross-references within your documentation. A symbol name in backticks generates a link, for example:

  • `MyClass` - a link to documentation for MyClass .
  • `MyClass.method(param1:)` - a link to documentation for that method.
  • `MyClass.method(...)` - shortcut syntax for the same thing.
  • `method(...)` - shortcut syntax to link to method from the documentation of another method or property in the same class.
  • `[MyClass method1]` - a link to an Objective-C method.
  • `-[MyClass method2:param1]` - a link to another Objective-C method.