Meeting notes: Swift documentation tooling workgroup (March 24th 2022)

Development Swift-DocC
1

Hi everyone, please find summarized meeting notes of the “Swift Documentation Tooling work group - call for interest (video call kickoff survey)” meeting below.

Attendees

  • daniel-grumberg
  • daveverwer
  • DavidBrunow
  • ethankusters
  • finestructure
  • franklin
  • hannahj
  • jack
  • Joseph_Heck
  • pbonneville
  • QuietMisdreavus
  • ronnqvist
  • taylorswift
  • tkremenek
  • theMomax
  • willimholte

Discussion

The main topic of the conversation was “How can we evolve documentation tooling in the Swift ecosystem?”

Joseph_Heck: I’d like for documentation tooling to support cross-module linking (writing a link to an API defined in another Swift module). This is also useful when you own a set of modules.

  • taylorswift: swift-biome allows you to do this.
  • jack: There are two interesting cases here:
    • Documenting multiple modules or an entire package as a single unit
    • Being able to reference other libraries that you don’t host yourself
    • taylorswift: how are we going to handle multiple URL schemes?
  • finestructure: As part of the Swift Package Index effort, we are considering building and hosting documentation for Swift packages, which might help with this. The build system is in place for that.
  • taylorswift: I’m concerned with this effort being duplicated with the swiftinit site. Perhaps we can explore integrations. It’s time for the Swift Package Index to vend an API to query the availability of symbols.
  • ethankusters: I think we should keep in line with the general Swift package philosophy. Being able to declare a base URL for your framework for easier integration when referencing other modules hosted on different servers.
  • taylorswift: Concerns with internationalization, support unicode in URLs.
  • jack: there was a proposal to turn non-alpha characters into hyphens, not great solution.

jack: I’d be interested in localization support for documentation.

  • Joseph_Heck: Yes, there is a strong desire from the community to have localized documentation.
  • jack: Yes, both for reading translated content and writing translations for content.
  • ethankusters: This might relate with the efforts to localize the Swift book? There is an interest in using standardized documentation tooling for the Swift programming language book.
  • daveverwer: A mechanism to visualize that there are differences between translated versions would be beneficial. It's unrealistic to expect all documentation to be immediately translated. Modification dates would be a good indicator, especially if the modification date for every translation (or at least every translation where the date differs) was displayed on each page.

jack: Also, I’m interested in the versioning of documentation, e.g., through tags.

  • taylorswift: lots of packages don’t have version tags, they have toolchain tags
  • Joseph_Heck: DocC has a concept of a bundle ID and that appears in links as well. There is also a version mechanism in DocC, and we need to make clear what versions mean. When do I need to specify a bundle ID/version number?
  • QuietMisdreavus: it would be nice to be able to view the history of the docs.
  • taylorswift: compressing data in an efficient format might be difficult. For example SwiftNIO has lots of tags; many duplicate data.
  • daniel-grumberg: documentation is text-based, compression algorithms may do a good job at de-duping text content.
  • franklin: might be good to also support viewing diffs of APIs across versions and see what documentation content has changed.
  • daveverwer: this has been on my wishlist for a while. Some kind of mechanism to see the progress over time would be really great.
  • willimholte: typo fixes have a different value in documentation changes. Do we want to allow hiding some changes and selecting what changes to display
  • daniel-grumberg: can reasonably detect changes that only affect API rather than docs
  • finestructure: Swift 5.6 has a new command to highlight API changes across tags. Might be possible to integrate that with documentation somehow.
  • finestructure: is there a stable format to refer to a symbol?
  • franklin: The Swift compiler uses USRs to uniquely refer to a symbol.
  • taylorswift: swift-biome also uses USRs
  • tkremenek: USRs might not be as rich as a concept for identifying an API over time. Is the USR the right tool to use for API changes tracking? USRs exist for both Clang and Swift. It’s a good identifier for a snapshot of the library, but for the evaluation of an API over time, do USRs make sense? Some APIs don’t have a binary compatibility concern. USRs are very tightly coupled to the definition. Might need another concept on top of that for tracking changes.
  • ethankusters: If I add an overload, I want to know that an overload was added rather than the previous function was deleted.
  • daniel-grumberg: introducing symbol versioning at the doc level or the ABI level could be interesting. Some other languages have that concept.
  • tkremenek: Also the question of “what does versioning even mean” needs to be discussed. How is it different to binary compatibility?
  • daveverwer: versioning of documentation and of APIs are related but different things
  • pbonneville: how can documentation best surface API changes, doc comments?
  • daniel-grumberg: also being able to highlight that specific doc comments have improved.
  • pbonneville: Automatically add a note for when a documentation was last changed, versioning for a specific document.
  • daniel-grumberg: is this something that would be authorable or automatically generated?
  • pbonneville: plugging into the commit history would be interesting
  • Joseph_Heck: “When was this latest updated” can be incorporated in articles, reference docs. And also the idea of API changes.
  • ronnqvist: interesting that there are differences between symbols/new APIs, but also curation changes, new code samples, etc. Need to aggregate diffs over versions rather than on the fly taking two archives—enriching diff data over time.
  • franklin: there might be parallels with documentation coverage, documentation diffs is interesting for authors to see how their docs have improved
  • pbonneville: Starting simple, with a “last changed” date?
  • ronnqvist: A page of documentation might have different sources, e.g., from doc comments in source or in documentation catalog via documentation extension, snippet file—how do you determine the versioning?
  • taylorswift: how does this compose with package versioning?
  • ethankusters: do we want to directly tie documentation versions to package versions? Might be good default. People will want to update docs without updating their package. Some might not use versioning.
  • taylorswift: Use the patch version?
  • daniel-grumberg: Patch version might not be the right tool if people are using the patch for functional changes only.
  • tkremenek: SwiftPM can evolve as well. The versioning scheme could be enriched to consider documentation. Should there be a notion of documentation identity for non-packages?
  • pbonneville: In the same way there is Package.swift with versioning, maybe there could be a configuration file for documentation catalogs.

taylorswift: it’s too early to issue recommendations for documentation, first need to build the tooling

  • tkremenek: Agreed. Although it is still good to discuss potential arcs, there might be areas to prioritize.

ethankusters: I’d be interested in continuing to improve the out-of-the-box CLI experience. SwiftPM plugin infra is a good way for integrating documentation generation. Many languages have doc generation support out-of-the-box. Might be interesting to have that in Swift as well, showing up in swift help.

  • Franklin: Yes, and I think it’d be interesting to explore the long term goals for hosting documentation. Swift-DocC added support for being hosted on GitHub Pages in Swift 5.6, is that the right long-term solution?
  • taylorswift: GitHub Pages isn’t great for hosting docs over time. Links change, no way to redirect links.

Joseph_Heck: When I’m adding code snippets, I’d like to be able to include the same ones into different places without copy/pasting. Include? Snippets?

Joseph_Heck: When documenting internal APIs, documenting for developers of the packages not users. Ability to jump to source.

  • taylorswift: How would it work if the other package is the same URL scheme that you are? Each hosting provider (BitBucket, GitHub) might have different ways of representing files/lines
  • QuietMisdreavus: having a package define its base URL would help.

taylorswift: could the Markdown package support Collections rather than Sequence? Elements come as LazyMapSequence which aren’t Collections.

franklin: support for more languages, consistent documentation tooling regardless of what language you define your API in. The Swift community’s main language is Swift, but there are others, e.g., Objective-C, C++, REST APIs.

  • tkremenek: Agreed. Bridging the gap to what Doxygen supports would be interesting.

Next steps

The group then discussed next steps, i.e., for each of us to think about what areas we’d be able to contribute to and in what capacity. Discussion can continue in the forums.Ted and Franklin will follow up with the attendees of this meeting.

12 Likes
2

Overriding the base URL probably isn't enough - IMO it would be better to assume a completely foreign documentation structure (perhaps emitted by jazzy or doxygen), rather than requiring everybody to use a compatible path hierarchy and query format.

I could imagine some kind of build-time solution. Each package declares where its canonical documentation lives (perhaps in its manifest). When you build the docs, DocC downloads an index for each package that your docs link to, and uses the index to construct the foreign links. The index file doesn't need to be very complex - it could just be a bunch of regexes or another basic pattern string (or even a Swift script?).

It would be nice if it supported versioning (e.g. resolve stable links to the v.1.4 version of package X's docs vs. resolve links to the latest version of package X's docs).

I wonder if there is some confusion here between versioning documentation itself (e.g. creating "documentation diffs" and adding last-update dates), and having stable documentation for versions of libraries.

I'm doing a basic version of the latter with WebURL's docs. They get built automatically by GitHub Actions - main always gets updated, then it checks to see if the latest tag also has docs, and if it doesn't, it switches to that tag and they also get built. It's a bit suboptimal, but it avoids race conditions because only one worker is updating the gh-pages branch at a time.

Pre-DocC | https://karwa.github.io/swift-url/0.2.0/
0.3.0    | https://karwa.github.io/swift-url/0.3.0/documentation/weburl/
0.3.1    | https://karwa.github.io/swift-url/0.3.1/documentation/weburl/
main     | https://karwa.github.io/swift-url/main/documentation/weburl/

There are still some things I would like to add to this - such as configuring DocC-Render to recognise this URL setup, and show a notice if you're not viewing the latest stable version of the docs, or add a link to view the main-branch version.

API diffs are interesting; adding/removing an API is only one piece of temporal information about a library/package. Why would we have such rich support for telling you how individual symbols changed, but no support for other information which accompanies a release, such as changelogs or edited release notes?

I also think it would be interesting to add notes from the future. For example, we may want to warn people viewing historical API pages that a catastrophic bug was discovered shortly after, or that there are particular security advisories to be aware of.

If a central location for temporal/cross-version information is added to DocC, it would be good to think broadly about what could be done with that space.

3 Likes