title says it all. the lack of stable urls to pages like Array.count make it hard for educational resources, API docs, and swift-aware typesetting software to reference standard library symbols.
the various sections under the symbol directory like “Adding Elements” in Array also do not have html id’s, and cannot be referred to. this means anyone writing a tutorial trying to reference a group of APIs on a standard library symbol has to direct visitors to the top of the page.
Is the URL to Array.count that you posted not stable?
What is this part:
https://developer.apple.com/documentation/swift/array/2943906-count
^^^^^^^^
I think the issue here is expressing overloads and different parameter labels.
Swift.Array.randomElement(): swift/array/2994747-randomelement
Swift.Array.randomElement(using:): swift/array/2994749-randomelement
Parameter labels are easy enough to include, but I’m not sure how you’d differentiate overloads without ending up with an arbitrary ID anyway.
Personally, I’m more concerned that the Swift Standard Library’s definitive documentation is hosted on Apple’s website and not using DocC.
How about using symbols’ mangled names as url path components?
Is that platform-independent?
the issue is not limited to symbols with overloads. associatedtypes cannot have overloads or argument labels, but they also have irregular urls:
https://developer.apple.com/documentation/swift/sequence/2908099-element
~~~~~~~
why can’t we just disambiguate with type context?
"Foo.bar(x Int:y:)"
"Foo.bar(x Sequence:y:)"
"Foo.bar(x some Sequence:y:)"
Is there any reason to believe that these URLs aren't stable though? I agree that having a random number in there is perhaps sub-optimal from an aesthetic POV, but that's a different issue.
it’s a problem because tooling and Swift-specific typesetting software cannot programmatically generate links from doccomments alone. they need to make network requests to apple.com and crawl the parent pages.
I believe that number is a hash of the symbol identifier, as is typical with DocC:
Both methods have an identical symbol path of
SlothCreator/Sloth/update(_:). In this scenario, and to ensure uniqueness, DocC uses the symbol’s unique identifier instead of its name to disambiguate. Use Xcode’s code completion feature — which you can invoke by pressing the Escape key or Control-Space — when adding the symbol link to insert the correct identifier for each symbol.### Updating Sloths - ``Sloth/update(_:)-4ko57`` - ``Sloth/update(_:)-jixx``
The real issue is that the Swift Standard Library’s documentation isn’t hosted elsewhere. Personally, I think it should be hosted on the swift.org domain or through a GitHub page, using DocC.
Speaking of which, a permalink shouldn’t change even if the standard library did. If I want a stable link to documentation like that, I usually link to specific lines in a specific file in a specific GitHub commit.
Sure, but like @Jumhyn I’m interested to know whether these links, once discovered, are stable. These are two distinct issues here.
That is the plan.
To get started, generated documentation for the Swift-DocC project itself is hosted at swift.org/documentation. Longer-term goals include adding documentation to more packages, as well as migrating documentation for the standard library and other documentation across Swift.org. This will make it even easier for the community to participate in documenting and teaching Swift.
Swift.org blog: Swift-DocC is Now Open Source, under the heading "Adoption"
I forgot about that, thanks for the reminder.
In that case, this whole topic is more or less moot: any remaining issues would be with DocC itself.
Wow, I had missed that part of the DocC announcement. Fantastic news!