I am not sure if I was just reading some previous Xcode 13 release notes over optimistically, but it seems that we will be able to generate DocC documentation for the base app, not just Swift Packages and frameworks. Is this actually the case and, if so, is there any documentation of how / when we will be able to do this?
Other than the change of some documentation page titling, "Produce rich API reference documentation and interactive tutorials for your Swift app, framework, or package.", I have not been able to find more information.
As it's all still evolving, there's no specific mention, but the pattern right now seems to be defaulting for "apps" (or any executable deliverable) to exposing the internal protection level symbols as a default. There's some related code to setting this specific preference in the swift package manager swift-docc-plugin codebase.
In practice, I noticed this was a possibility in Xcode 13.3 beta2, and continues to operate the same way in 13.3 beta3. And like a library, it'll leverage a documentation catalog. The DocC team seems to have some of their own internal DocC documentation in their codebase very much along these lines, which you can see in that repository at swift-docc/Sources/SwiftDocC/SwiftDocC.docc at main · apple/swift-docc · GitHub if you're curious. Open it with Xcode, build the documentation, and you'll see the results in the documentation window as you'd expect.
Thanks for the info Joseph. Interesting developments. It does not look like they have not publicly documented and released a way to generate documentation for an app (project level) as of yet.
Documentation New Features
Xcode can now build documentation from your Swift code in executable targets, like apps and command-line tools. (79155998) (FB9156246)
When building documentation for an app in Xcode 13.3 (currently in Beta), DocC will generate documentation for internal, public, and open symbols. If that's not working for you, I would really appreciate it if you could file a Feedback report (since this issue would likely be related to Xcode rather than the core Swift-DocC compiler) with more details about your project and the Apple team will follow up.
Yes, that's right. If you look at build logs after building documentation in Xcode 13.3, you will see what flags Xcode is passing to Swift and DocC invocations when building an app.
Does this only work for apps that leverage SPM?
I am using cocoapods for my dependencies and somehow DocC does only generate documentation for my own frameworks and for a couple of cocoapods dependencies.
Looking at the Build Documentation report I can see that there is a "Compile documentation" step for every target including the app itself, but DocC is not generating the documentation for the app target.
I've also tried to add a documentation catalog inside the app target, but unfortunately this does not make a difference.
Did you try naming the default documentation .md file and the catalog the same name of your module? Not 100% sure if that is the issue, but that is what worked for me.
This should work for any application target that includes Swift source code, regardless of their SPM usage. You shouldn't need a DocC catalog at all documentation to be produced, it should work just based off of the doc comments in your source file.
If you're running issues, a Feedback report with your project and the build logs you're seeing attached would be really helpful. We'd really like to track down any problems here.
Thanks for the fast answer. Sadly I cannot share build logs for the project, but maybe I can try to reproduce the issue in a sample project.
I just retried generating the documentation and it could be that this is an issue with Xcode 13.3.
If I use the "Build documentation" functionality from Xcode it does not generate documentation if I select the apps scheme.
If I select a framework as scheme and generate the documentation, it generates documentation for the frameworks inside the workspace and for some cocoapods dependencies but not for the app itself.
Generating the documentation via CLI works as expected if I specify the apps scheme. I am not sure which command Xcode is executing when using the "Build documentation" option from Xcode.
Maybe Xcode is doing the right thing but the documentation does not show up in the documentation Viewer?
Sadly I cannot share build logs for the project, but maybe I can try to reproduce the issue in a sample project.
We would still appreciate a Feedback report with any information that you can share. If you can't reproduce this in a sample that can be attached to the feedback, I can try and provide some pointers on how to find information that would help helpful to include in the Feedback report.
Looking at the Build Documentation report I can see that there is a "Compile documentation" step for every target including the app itself, but DocC is not generating the documentation for the app target.
Since there is a Compile documentation step for the app target, it looks like Xcode has correctly identified that it should generate documentation for the app target.
If you expand the step to reveal the full command line invocation to docc it should show that the path where DocC writes the .doccarchive (the --output-dir argument) and the path to the input DocC catalog (the input before any flags or options) and input directory of symbol graph files (the --additional-symbol-graph-dir argument). After the build succeeds you can check if a .doccarchive exist at that output location and if opening that .doccarchive adds it to the Documentation Window in Xcode. Both of those are helpful information to add to a Feedback report.
If no .doccarchive exist at that location, then it would help to know more about the input to DocC. The two most useful bits of information to include—without attaching any build files—would be:
Does the directory hierarchy at the path that's passed for the --additional-symbol-graph-dir argument contain any symbol graph json files?
If it does, do they contain any "symbol" and "relationship" entries?
If a .doccarchive exist at that location and can be manually opened in the Documentation Window, then it will be hard to investigate without a buildable sample project. Still, it would helpful to attach the command line invocations to DocC for all "Build documentation" steps for all targets in the build log to the Feedback report. This would provide most of the value of having access to the build log. If you prefer you can replace fallback bundle names and fallback bundle identifiers with placeholder values but make sure that they are used consistently so that it shows for example if two different documentation archives use the same bundle identifier.