I've started digging in and experimenting with the documentation coverage metrics, as a way to just track how much API surface exists on the library I'm contributing into, and to track updates over time.
(FYI: All of this is with the version of DocC included with Xcode 13.1)
After a bit of digging in the code and experimentation, I ended up using the following pattern:
- make an explicit symbol graph directory
- run the swift build with the
-emit-symbol-graphoption aimed at that directory
- run a
docc convertcommand to expose the coverage metrics.
An example of such:
mkdir -p .build/symbol-graphs swift build --target Automerge \ -Xswiftc -emit-symbol-graph \ -Xswiftc -emit-symbol-graph-dir -Xswiftc .build/symbol-graphs xcrun docc convert Source/Automerge.docc \ --fallback-display-name Automerge \ --fallback-bundle-identifier org.automerge.Automerge-swift \ --fallback-bundle-version 0.1.6 \ --additional-symbol-graph-dir .build/symbol-graphs \ --experimental-documentation-coverage \ --level brief
brief metrics output:
--- Experimental coverage output enabled. --- | Abstract | Curated | Code Listing Types | 40% (10/25) | 96% (24/25) | 0.0% (0/25) Members | 3.2% (16/507) | 74% (374/507) | 0.20% (1/507) Globals | 2.9% (1/35) | 97% (34/35) | 0.0% (0/35)
(By the way, a HUGE THANK YOU!!!! for including a detail that shows how many of the samples include a code listing, that's just amazing!)
This particular library has a dependency to another library (ZippyJSON), and I didn't want to include it's symbols into my coverage metrics. The solution I've found for now is to explicitly remove it's set of symbols from my
symbol-graphs directory, but that's kind of awkward and specific to this package.
Is there a way to "exclude" a set of symbols (other than removing them) for the purposes of getting these metrics (or likewise, getting hints from the
When I run out a detailed "report":
# exclude ZippyJSON symbols from analysis rm -f .build/symbol-graphs/ZippyJSON.symbols.json xcrun docc convert Source/Automerge.docc \ --fallback-display-name Automerge \ --fallback-bundle-identifier org.automerge.Automerge-swift \ --fallback-bundle-version 0.1.6 \ --additional-symbol-graph-dir .build/symbol-graphs \ --experimental-documentation-coverage \ --level detailed > report.txt
The report is sort of a table, with the synopsis at the top, but sort of not. Is there any consideration to getting the detailed output report in a structured format of any kind? CSV perhaps?
What does the
USR field that is reported represent?
Symbol Name Kind Abstract? Curated? Code Listing? Parameters Language USR applyPatch(patch:) | Instance Method | true | false | false | 100% (1/1) | Swift | doc://org.automerge.Automerge-swift/documentation/Automerge/Document/applyPatch(patch:)
USR something that we could potentially use to link documentation between frameworks?