1

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

There was a pitch from @taylorswift that I expect the documentation workgroup would be interested in discussing:

In particular:

Currently, developers such as myself are in a difficult position where we would obviously like to support the advanced linking features of Taylor's swift-unidoc engine. However, given DocC's weight in the ecosystem (it is included in the toolchain and powers Xcode documentation), in case of any future divergence, we would need to prioritise DocC's way of doing things.

I don't have an opinion on the technical details of the link format. I think it's great that members of the community such as @taylorswift care so much about improving Swift's documentation tooling (it has clearly been a large time commitment), and I also think this should not be a competitive feature -- that package developers shouldn't have to worry about incompatible link formats. But that's as far as my opinion goes. I'd just like to encourage everybody involved to work something out.

6 Likes
3

+100 on every point here, especially w.r.t. gratitude to @taylorswift for this (and their other) work on improving Swift documentation.

5 Likes
4

Thanks for bringing attention to this pitch! @taylorswift is this something you'd like to discuss in the next workgroup meeting?

5

yes, that sounds like a great idea! i'm particularly interested in seeing what can be done about DocC linker warnings and whether we can make it forwards compatible with the new format even if this doesn’t end up being an implementation priority for the team.

i was going to suggest it as an agenda item later this weekend, but it looks like @Karl beat me to it :slight_smile:

6 Likes
6

I can't make it to the meeting on Nov 6. Would it be possible to have the link syntax discussion on Nov 20 instead? It would probably be good for me to be part of that discussion considering my experience with link resolution in DocC and the DocC link syntax.

7

i'm not sure if bumping this to the Nov. 20th meeting is a good idea, as it overlaps with Thanksgiving, so even more people are likely to have conflicts then. experience in the software industry has taught me to expect no availability through the month of December due to holidays and vacations, so bumping this discussion effectively means efforts will be frozen until Q1 2024.

i doubt that Monday’s meeting will be the last time we discuss standardizing the codelink syntax, so i suggest we begin discussions then and revisit the topic as needed in January.

8

Oh, I should have looked in my calendar before blindingly adding 14 days to a date.

I agree with your assessment; Nov 6 sounds like the best meeting to start this discussion.

I've been out for a couple of weeks but I'll be back later next week. I'll take some time to read the pitch and reply in the forums thread then.

2 Likes
9

Meeting notes:

  • Unified symbol link format
    • Kelvin: Support vector links, adds support for using ‘.’ and multiple components at once
    • Ethan: Well written proposal; I’m wondering if some of these can be split up. I know David has a proposal to address disambiguating suffix syntax. Both of you have very good ideas and we should see how we can move forward will all of these.
    • Ethan: Is there a need to land all the changes at once?
    • Kelvin: Syntax makes less sense if split up.
    • Ethan: Vector based links will be more digestible. The disambiguation syntax is different and folks need to learn it.
    • Alex: For context, DocC doesn’t show intermediary path components because we didn’t have a need for it in the past.
    • Kelvin: It’s mainly for namespacing which is more common in third party libraries.
    • Kelvin: Formalizes David’s proposal on a leading slash indicating an absolute path.
    • Joe: Vector syntax makes a reasonable amount of sense, but as a writer, how do I know what’s available to me? The recent changes in DocC has made that process harder. Need to rely on code completion. I’m not sure if this proposal makes this easier or harder to determine what the right link should be.
    • Kelvin: As a future direction, looking to support linking to an overload family.
    • Franklin: Not clear to me about splitting vector and disambiguation syntax.
    • Kelvin: Something to keep in mind. Can provide feedback on forums.
    • Franklin: Vector syntax addresses a real need. Could a global option also work to avoid new syntax?
    • Kelvin: Shouldn’t be confusing to use ‘.’ vs ‘/‘. Newcomers will use ‘.’
  • Sven
    • Audited DocC archive size changes after disabling synthesised symbols. Wouldn’t have that much effect if enabled.
    • Joe: Library that has lots of SwiftUI view conformances has drastically reduced size.
    • Sven: Are these conformances symbols useful?
    • Joe: Didn’t add a lot to the project.
    • Sven: Would you be able to enable the protocol inheritance behaviour for a single symbol?
    • Joe: No. It would probably make more sense to control this at the package level.
    • Max: Might want granularity within a package. For example, for SwiftUI.View, it makes sense to disable, but for others, you might want to enable it.
    • Ethan: Agreed; what is the right universal default? Is it reasonable to turn off by default and add support for more granular control as a next step?
    • Max: I would be worried about turning off by default.
    • Ethan: It seems notable to be that the packages that do need it are exceptions like the standard library.
    • Max: From a newcomer, it’s useful to see where functionality comes from.
    • Daniel: File size problem is a symptom of not being able to dedupe these pages in the archive.
    • Sven: No longer an issue for Swift Package Index.
    • Daniel: Maybe we should split the topics section to show inherited symbols.
    • Max: Agree with Daniel there is a good technical solution. There should still be an option to turn synthesised symbols off.
    • Franklin: Less symbols also means faster builds.
    • Max: Is documentation generation time a concern?
    • Franklin: It helps lower the impact over the overall build.
    • Daniel: Do incremental documentation builds help on SPI?
    • Sven: No, clean builds for documentation.
    • Sven/Dave: Had pushback around building documentation by default since some folks already had their docs published elsewhere.
    • Daniel: Regarding de-duping, can boil things down to single page conceptually, or keep multiple pages but that share data.
    • Joe: Need cross-module linking to make this story better. A flag to disable would do the trick for now.
    • Daniel/Max: Orthogonal to cross module linking to me.
    • Ethan: Need to make proper flag to disable the behaviour.
1 Like