Documentation Workgroup meeting: December 4th, 2023

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

  • Continued discussion around disabling synthesized symbols and inherited protocol documentation by default.

Please propose any additional agenda items in this thread.

1 Like

Meeting notes

  • Kelvin: Should keep synthesized symbols, they’re part of the API.
  • Victoria: Without the synthesized symbols, the protocol conformances are still there so you can access the information, but not as readily seen.
  • Kelvin: Worries it won’t be accessible for newcomers. In Standard Library for example you do expect the APIs to show up and I think most libraries are structured like it.
  • Alex: I think the standard library is pretty unique in how deep its protocol hierarchy goes.
  • Kelvin: In the sense that you implement the core behaviour of the protocol, but use the default implementation.
  • Alex: Showing only what this type defines allows you to focus on what this type defines.
  • Kelvin: Maybe 2 sections would work, one with implemented APIs and another one for inherited.
  • Sven: How do these synthesised symbols show up?
  • Franklin: We generate an API collection page with synthesized symbols of no content (if the protocol is defined externally)
  • David: Does it make a difference if the protocol you’re conforming to is defined in your module or a different module?
  • Victoria: Would it be helpful to drop the protocols implementation page since you can access the protocol’s documentation?
  • Kelvin: You’d need to click through all the conformances to find the information you’re looking for.
  • Victoria: Synthesized symbols are already tucked away in an API collection.
  • Dave: If we leave it on by default for the tool, it would be confusing to turn it off on SwiftPackageIndex.
  • Franklin: Would be less confusing for the user for the experience to be consistent whether that protocol is defined in your framework or not.
  • David: When it’s a local protocol though, we can link you to the page which has the most complete content.
  • Franklin: If we’re able to provide a link to a protocol (either because it’s local or externally resolvable), should we show that link instead of listing the synthesised symbols?
  • David: Yes, and for synthesized symbols, should we just generate a single instance of protocol implementation pages?
  • Kelvin: What about generic constraints?
  • David: Currently we display all the methods from the extensions but show a line below the API what the constraints are.
  • Alex: Reminds me of an approach we talked about years ago. For class based inheritance, do we want the same behaviour? One idea that was discussed was an API explorer mode. In that mode, you’d be able to constrain what you’re seeing based on constraints you can choose.
  • Sven: There is value if you can switch to view all the symbols.
  • Franklin: Reminds me of how you can use headers to browse some APIs declared on the type, and use autocomplete to get an exhaustive list.
  • Kelvin: There are cases where APIs are never available. Would be nice to filter.
  • Alex: You’d need to have the generics constraints solver to do that accurately.
  • David: Feels like we’re steering away from the conversation about synthesized symbols.
  • Franklin: Current proposal is to deduplicate protocol implementation pages for non-resolvable protocols, and just link to the protocols for those that can be resolved.
  • Victoria: Edge cases around constrained APIs since they’re defined based on the subtype. Would need to compute some kind of union set across all the subtypes.
  • Kelvin: I don’t think this would scale well on large packages.
  • Franklin: We could lower the deduplication to the synthesized symbols?
  • David: Do we even need those pages since they’re empty? We could list the links as inactive links.
  • Franklin: Yes and make them active when we can resolve them.
  • David: This would be the ideal scenario but would have similar issues with constraints. One idea is that if the protocol implementations page has info we want to preserve (ie constraints) we don’t deduplicate that content.
  • Victoria: What if we transform the implementations page to be a collection of declarations and group them by constraints?
  • Franklin: Would we still have an implementation page to subtype?
  • Victoria: Yes.
  • David: And we can always explore de-duplicating the implementation pages at a later stage. Declaration is richer than their title?
  • Franklin: Would we still support linking to synthesized symbols?
  • Victoria: No, we’d drop support for that. Likely you’d want to link to the real symbol.
  • Franklin: Does this apply to just local protocols or external too?
  • David: We could keep the same model for both local and external and make it links for the local case.
  • Victoria: We can display the declarations in both cases, but also show links for resolvable links. You can author a link to a synthesised symbol.
  • Franklin: Feels like a good solution towards the direction we want to go in would be to keep the model as is, but deduplicate synthesised pages. We’d lose the ability to link to synthesized symbols.
  • Victoria: We could still make that work by implementing alias URLs for pages.
  • Kelvin: Can implement client side redirects.
  • Sven: Seems like we’re dealing with two problems, file size and UX. File size is no longer a problem for SPI.
  • Franklin: I’d still like to tackle the file size problem.
  • Kelvin: Do we have stats on the total of archives sizes?
  • Dave: about 100GB, 13M files uncompressed
  • Sven: Need to consider multiple versions for archives.
  • David: Our deduping logic would apply for all kinds of packages.
  • Sven: Would apply for future archives.
  • Franklin: Do we want to move forward with the solution that reduces file size? Open questions of whether we continue supporting linking and potential symbol graph changes?
  • @ronnqvist: Sounds good. I can take an action item to file an issue about what the model we’re discussing today.
  • Franklin: Seems like a good next step. If there are more thoughts on UX improvements, let’s discuss them in a future meeting.
1 Like