Documentation Workgroup meeting: July 17th, 2023

Swift Documentation Workgroup Updates
1

The Documentation Workgroup will be holding its next meeting on Monday, July 17th, 2023 from 8:30am to 9:30am PT (or see the time in your own timezone).

This meeting will be open to anyone who wishes to contribute. If you wish to participate, please reach out to @swift-documentation-workgroup in forums via DM for a link to the WebEx meeting.

Meeting notes for this meeting will posted in this thread shortly after.

Agenda

  • Upgrading minimum tools version in Swift-DocC repos (@Kyle-Ye)

Please propose any additional agenda items in this thread.

2 Likes
2
I’ve been meaning to suggest some breaking changes to the existing ExternalReferenceResolver API and ExternalSymbolResolver API which I think would be good to discuss both in a Forums thread and in Workgroup meeting.

I don’t know which would be best to start with.

I think it’s better to start with the Forums post.

1 Like
3

Meeting Notes

  • @Kyle-Ye: Is it okay to bump the Swift tools version for Swift-Markdown?
    • Yes, we want to maintain compatibility for folks that haven't had time to update yet, but Swift 5.7 was released a year ago. It's okay for DocC to be using more recent versions since it's primary a toolchain product.
  • @daveverwer: DocC archives produce many files
    • Should synthesized symbols not be emitted by default?
    • Victoria: Compiler has support for omitting protocol conformances unless they have documentation
    • Kelvin: Synthesized symbols contribute to an increase of 2x, there are other areas to explore to reduce the number of files.
    • Dave: Like the idea of changing the default
    • David: should look at examples, look what the impact is. Are we losing information?
    • Kelvin: Change behaviour of the flag to remove all synthesized symbols?
    • Victoria: There is already a flag for to control that.
    • Max: Should this be a per package setting rather than controlled by the invocation? For example if you extend a type from a package where you’d want the synthesized symbols where the package author did not.
    • Ethan: There is complexity this would introduce, could be confusing for users as to why these symbols appear sometimes and not others.
    • Sofía: --experimental-skip-synthesized-symbols in the plugin, should this be the default, or remove the experimental word?
    • Ethan: I like the experimental word because it allows us to do more exploration here as to what the right default behaviour. Don’t think this behavior should be flag-based, it should be defined in the package. Maybe the -skip-protocol-implementations should be the default?
    • Kelvin: I think this should be configurable at the protocol level.
    • Ethan: It seems reasonable to have the default off and for protocols being able to enable it maybe via the documentation attribute.
    • Max/Victoria: Cumbersome to implement in the Swift compiler. Hard to say what the benefit would be.
    • Max: For example for SwiftUI.View, you’d want to disable that, but for other protocols, it’s useful to see the synthesized members.
    • Franklin: Also if you conform to a protocol outside of your module, you can’t access that documentation via a link.
    • Ethan: Think this makes documentation easier to navigate. We should look at more examples. Could we build a popular packages with the flag? Can we pipe the protocol conformances flag to the DocC plugin?
    • Victoria: Need to check if that flag is available in the extract command.
    • Max: Don’t think it’s possible via SwiftPM.
    • Kyle: Complex protocol hierarchies are sometimes better hidden. For example you want to look at Int and know what its members are, without needing to know where they come from.
    • Alex: Confusing behaviour when documentation gets inherited. For example Array/Dictionary inherit documentation from Sequence but use Array examples. Difficult problem to solve, had similar issues in Objective-C documentation. For example if I’m new to UIKit, I need to walk the type hierarchy to see what members you actually have access to. For Swift it’s similar, and you can conform to multiple protocols. When you’re new you might want to see everything, and as you become more familiar, you might want to see less and less.
    • Max: this conversation started with getting size of archives down. Maybe removing symbol pages isn’t not the right solution. There might be opportunities to reduce size while continuing to include these symbols, and the frontend could control what gets displayed.
    • David: Could be a readability issue to include too many symbols.
    • Dave: We see it on SPI as separate issues. The usability of that documentation is the main concern.
    • Ethan: Interesting that SwiftUI and standard library have separate opinions. The right default solution is non-obvious.
    • Kyle Ye: Maybe this could be controlled at 3 levels, protocol level, package, and browsing (a show all toggle).
    • Ethan: Will add support to skip protocol conformances
    • Sven: Can re-generate docs with the skipping flag on.
    • Dave: Might be beneficial to look at smaller packages as well.
    • Sven: Also a concern that there are many links, too many for search engine sitemaps.
    • David: Versioning issues as well, what version of the standard library do we link to?
    • Sven: Could use the compiler version that the documentation was built with.
    • Franklin: Can also think about reducing duplication across synthesized symbols
  • Kyle Ye: Any reason plugin only supports Swift targets?
    • Ethan: There’s remaining work in SwiftPM to add support to invoke clang extractapi. I have a PR up.
1 Like