Documentation Workgroup meeting: March 27th, 2023

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


  • @binamaniar will present the GSoC project on localization she is putting forward.

Please propose any additional agenda items in this thread.


is this the correct date?

Good spot, fixed it the correct date is March 27th.

1 Like

Your external link is incorrect. It should be:

Discourse date/time:

Monday, March 27, 2023 3:30 PM Coordinated Universal Time


We could briefly discuss testing of custom docc parameters in SPI Add support for custom docc "build" flags · Issue #2303 · SwiftPackageIndex/SwiftPackageIndex-Server · GitHub

1 Like

Let's do it! Bina is unfortunately unwell so we won't discuss the GSoC project.

hello, sadly I'll not be able to make it to this meeting

Here is the TSPL branch where I'm outlining the new Macros chapter, which I mentioned in today's meeting:

When I have a good outline, I'll post a pitch thread on the forums to invite review of the outline and approach.

1 Like

Meeting notes




Ethan: GSoC proposal around localization for Swift-DocC has been put forward Render team has been working on localization, Marina especially has been driving this work, it can accept a different directory for localized content, looking at locale etc. Project is about minimal support for this in DocC itself, the initial scope is about one md file per language, many details about this but not so much about complex changes in DocC, not fully feature complete.
Kelvin: not doc comments in source files?
Ethan: Doing a documentation overwrite file is how this would work to limit the scope but we would want to support this down the line.

SSWG blog post

Dave: Link is here and no issues have been brought up.
Post is not yet complete, some sections are missing. If people want to provide more feedback

SPI DocC flag

Sven: new field for custom parameters for the docc command in the yaml file. For SPM based build SPI uses the plugin and xcodebuild otherwise. As the author you have to make sure that the flags are the same. Add support for custom docc "build" flags · Issue #2303 · SwiftPackageIndex/SwiftPackageIndex-Server · GitHub custom_documentation_parameters

Ethan: Swift Syntax want to dogfood for the synthesized symbols removing flag.

Swift Macros

Victoria: has been playing with this for the last couple of weeks. Doug Gregor put up a demo project with macros (insert name here).

Two pieces to a swift macro:

  • actual type that conforms to a protocol
  • in a separate declaration we have a macro declaration.

The documentation shows up correctly but the declaration still has the external macro piece which feels redundant.

Max O: There is a question of what documentation for APIs generated macros.

Daniel: There is a high-level question of how do we keep on top of these things?

Ethan: People have been mentioning documentation impacts for this feature a couple of times in the forums. We should probably start a conversation with formalizing documentation impacts in the evolution process.

Victoria: Rust community, each RFC has a section about teaching the feature. We could have a similar section in the evolution template, that would highlight impacts on documentation.

Daniel: This ties in with TSPL, Alex any thoughts?

Alex: Public work ongoing on a branch, PR when fairly stable, sounds like it will be a new chapter in the book.

Ethan: We are too late in the release for this to have an impact. We should have a thread in the current evolution proposal about this aspect of the process.

Kelvin: We can't make an evolution proposal about process

Alex: Forums is about gathering feedback before we reach out to the core team members. I have the ability to bring it up to the lanuguage working group as I attend biweekly for documentation purposes.
Workgroups are fairly young, there is no process for the workgroup to bring something up to the core team, we need an official process to about the speaking in the void feeling.

Dave V: In the website WG they make sure that someone from Apple takes it to the core team

Daniel: That seems like enough of a motive to start a thread about formalizing process to bring something to the attention of the core team.