Documentation Workgroup meeting: September 11th, 2023

Swift Documentation Workgroup Updates
1

The Documentation Workgroup will be holding its next meeting on Monday, September 11th, 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

  • Reducing archive sizes

Please propose any additional agenda items in this thread.

2
  • Continued discussion on including synthesised symbols by default.
    • Sven: Enable skip synthesised symbols flags in SwiftSyntax for testing.
    • Ethan: SwiftSyntax team is okay for us to disable synthesised symbols.
    • Sven: Can open a PR for SwiftSyntax.
    • Ethan: What are the other largest frameworks? Maybe we want to disable their synthesised symbols as well as we’re thinking about the long term solution.
    • Sven: The Stream library.
    • Dave: Reduced number of pages by half.
    • Ethan: SwiftUI-based frameworks would get a win from enabling this.
    • Franklin: What are next steps for whether we want to exclude by default?
    • Sven/Dave: Would be in favour.
    • Ethan: Question is whether it should be synthesised symbols or inherited symbols that should be excluded. We should come up with counter-examples where this is worse.
    • Kyle Murray: Is this the change that would make Array empty for example?
    • Ethan: Yes. Maybe we want to instead automatically curate pages rather than synthesising them.
    • Alex: Not sure whether the preferred approach for standard library is to have specific documentation for synthesised symbols, or to traverse the protocol hierarchy’s documentation.
    • Ethan: Maybe we should consider how to make DocC such that the standard library isn’t a counter-example to how synthesised symbols are handled.
    • Sven: Was there another flag to try?
    • Ethan: Yes there is one for inherited docs but it’s not available through SwiftPM.
    • KyleYe: Does it mean Array and Dictionary use the same default implementation of Collection protocol requirements. But they use different curated docs?
    • Alex: Yes, the documentation gets inherited from the protocol.
    • David: Yes, even if the concrete type gets a custom specialisation.
    • Kyle Ye: Can you document a synthesised symbol?
    • David: Yes, you can via documentation extensions.
    • Alex: Would be quite a large effort to document each concrete type individually.
    • Kyle Murray: We could use a tab navigator to provide documentation for each concrete type in the protocol’s documentation. For example, specifically for code listings.
    • Ethan: Agreed, I’ve been thinking about featuring code listings more prominently and this should be considered.
    • David: Reminds me of a problem where when you curate a synthesised symbol, you lose context as to which protocol that symbol came from.
    • Kyle: ==(_:_:) | Apple Developer Documentation here, we show a note regarding where the comment came from.
    • Ethan: I’ll take an action item around what information we can display on the page for contextualising where a symbol comes from.
    • David: what are the next steps regarding turning off synthesised symbols? Is it just gathering more examples?
    • Ethan: Getting feedback SwiftSyntax, looking at getting more relationship data on the page, and looking at more examples.
    • Franklin: Which packages should we try this on?
    • Sven: Can get us a list of the top 10 packages that have lots of pages, and I can take the top few percent.
    • Ethan: We mentioned in the past that archive size isn’t the only concern, we want to improve the UX.
    • David: Also a concern that we’d be losing inherited cross-package documentation when turning this off.
    • Ethan: That’s a great point, maybe we need cross-module linking.
2 Likes