Hey everyone! I landed preliminary support for symbol graph generation in Clang for C/Objective-C projects in the Swift 5.7 Development toolchain. Symbol graph is the JSON file format emitted by the Swift compiler and consumed by documentation tools like DocC that describes the APIs exposed by a project along with the associated documentation comments. More details about symbol graph can be found at https://github.com/apple/swift-docc-symbolkit.
Trying out Objective-C symbol graph generation
To try out this preliminary support you will need to download a Swift 5.7 Development Snapshot toolchain released after May 18th 2022 as available at https://www.swift.org/download/. I have also provided a sample Objective-C framework available here. To simply see the end result you can just invoke the ./preview-docs script provided in the sample code.
If you are interested in the details here is a sample Clang invocation to generate symbol graph for a project called MyProject:
xcrun --toolchain swift clang \ # Alternatively just use the path to clang in the toolchain
-extract-api \
--product-name=MyProject \ # Name of the project
-o .build/symbol-graphs/MyProject.symbols.json \ # Output path
-isysroot $SDK_PATH \ # Path to the SDK as returned by `xcrun --show-sdk-path`
-F $SDK_PATH/System/Library/Frameworks \ # System frameworks
$HEADER_SEARCH_ARGS \ # Additional header search arguments needed by your project
-x objective-c-header \
MyProject/MyProject.h \ # Umbrella header if your project has one
MyProject/A.h \ # List of public headers in your project
MyProject/B.h
This command would generate the symbol graph saved as MyProject.symbols.json in the build/symbol-graphs directory.
You can then generate a DocC archive or preview the docs in the usual way and making sure you provide the directory in which the symbol graph for your project was generated using the --additional-symbol-graph-dir argument. For example to preview the docs for MyProject you can use the following command:
xcrun --toolchain swift docc preview MyProject/MyProject.docc \
--fallback-display-name MyProject \
--fallback-bundle-identifier org.swift.MyProject \
--fallback-bundle-version 0.0.1 \
--additional-symbol-graph-dir ./build/symbol-graphs
This command will start a local web server on port 8000. You can preview the documentation for your project by accessing http://localhost:8000/documentation/MyProject in your web browser.
SwiftPM integration
This is just the beginning of documentation tooling support for Objective-C in the Swift ecosystem. Now that it is technically possible to generate symbol graph files for Objective-C projects using open source tooling, I am looking at refining the end user experience. The aim is to provide seamless integration with existing Swift Package Manager documentation plugins (including the Swift-DocC Plugin) by enhancing the PackageManager.getSymbolGraph(for:options:) method introduced with SE-0332 to also return symbol graphs for Objective-C targets.