The C++ interoperability workgroup (@cxx-interop-workgroup) has put together a proposal for how to document Swift's support for C++ interoperability. I posted an initial draft PR with initial documentation page layout mimicking the current proposal: [cxx-interop] add initial 'Mixing Swift and C++' docu… by hyp · Pull Request #299 · apple/swift-org-website · GitHub .
High-level overview of changes for proposed C++ interoperability documentation
We propose to change the following page to mention C++ interoperability:
swift.org/documentation (Swift.org - Documentation)
A new section "Mixing Swift and C++" should be added to this page. Here's a preview of how it could possibly look:
The new section should appear between the existing "API Design Guidelines" and "Tools" sections.
This section will be similar to other sections on this page, as it will just link to specific documentation sub-pages. Right now, we propose linking to two documents:
-
swift.org/documentation/cxx-interop: Describes how Swift and C++ interoperate ("Read how to mix Swift and C++" in the screenshot above) -
swift.org/documentation/cxx-interop/status: Describes the support status of the interoperability feature ("Status of C++ interoperability support in Swift" in the screenshot above)
In addition to changing the existing documentation page, we propose adding several new pages to document Swift's support for C++ interoperability:
swift.org/documentation/cxx-interop
This is the main guide page containing the reference manual for using C++ APIs in Swift, and Swift APIs in C++. It's split into a number of various subsections going over each specific API pattern/language construct. This page provides numerous examples to illustrate the behavior of this feature to the user.
- This page links to both the status page and the project setup page somewhere in its introductory section.
-
swift.org/documentationlinks to it.
swift.org/documentation/cxx-interop/status
This is the status page shows what's currently supported in the compiler, and in which version of Swift the support has been introduced (starting with Swift 5.9). This covers both language features, and standard library features, in both directions. It also highlights some of the most important known issues as well.
swift.org/documentation/cxx-interop/project-setup
This page:
- Describes how to setup a new project using SwiftPM / CMake / other build environments using C++ interoperability, or how to add Swift/C++ to existing project.
- Links to SwiftPM and CMake samples that use C++ interoperability on Github.
Landing the initial set of docs
We would like to get your feedback on the proposed structure, layout, and the overall contents of the newly added pages. Let us know if this proposed structure fits well into the existing structure of the website, or if you would like to see any changes.
We will start updating the initial PR and making concrete additions to the new documentation pages over the next few days. We intend to converge to a PR that we think is ready to be merged in about 2 weeks. We then would like to merge the PR in about 3 weeks, around the end of May / start of June.
Once the initial PR is merged, we would like to keep updating and refining the documentation until Swift 5.9 is released to ensure users get a great user experience when trying interoperability with Swift 5.9. We anticipate that C++ interoperability will be more widely adopted starting with Swift 5.9, and that's why we think that prioritizing the documentation is really important for this release.
Please let us know if you have concerns about the proposal itself and/or the proposed timeline for merging the change to the website.