Just in case you might find it helpful there's another thread from another DocC contributor giving feedback about this feature Experimenting with documentation coverage metrics - a few questions and feedback - #3 by Joseph_Heck.
Hi, @sofiaromorales!
Thank you for the recommendation. Some of the points in that thread were really insightful. Since a good part of the GSoC project I want to work on involves making decisions on how to improve this feature, I’ve been gathering as much feedback as I can find to ensure these decisions are well-informed. Therefore these posts are quite helpful :)
Yes, that seems correct to me. CoverageDataEntry is the main place where the coverage data is calculated for each page. Each coverage entry is created by ConvertActionConverter during the "render" phase (since the CoverageDataEntry reads some data from both each page's model object and its render object). After all pages are rendered and have their coverage entries created, the ConvertActionConverter passes the coverage entries to an output consumer type which writes the data to a file within the archive output. This file is then read by the CoverageAction which prints a summary of the data.
Thank you so much for the detailed explanation! I’ve been taking notes on the pointers you provided, as well as insights and conclusions I’ve drawn from reading the code and forum discussions, and this has been incredibly helpful.
On a more conceptual level, I’ve noticed that the Project Idea and a couple of other forum posts mention the goal of “writing the coverage metrics in a new extensible format that other tools can read and display”. I’ve come across various pieces feedbacks that I believe correlate to this topic, such as:
- Making documentation metrics easily accessible for the Swift Package Index
- Exporting the data as a CSV file
- Displaying the coverage metrics available in the website preview
Given the variety of use cases, my understanding is that it would be better not focusing on one specific tool, but expanding the DocumentationCoverageOptions model to allow for a more granular control over filters and grouping the metrics. This would be a more flexible approach which I believe would benefit both developers and other tools. There have also been feedbacks aligned with this, such as the idea of revisiting the current flag options to ensure wether they're still relevant, and creating new ones that would allow for alignment between the organization of symbols in the detailed coverage metrics.
To gather ideas on customization options, I started looking into other tools with similar needs -mainly other documentation and testing tools. This brought me back to how intuitive and effective the interface for the test coverage in Xcode is. Although I believe this level of integration with Xcode exceeds the scope of the project, it seems like a very interesting reference. I also noticed some requests for clearer, more user-friendly fields in both the "brief" and "detailed" coverage data formats. Structuring the data in a way similar to Xcode's coverage reports could help address that as well.
Would love to hear your thoughts on this, as I believe it will be an important point on the project!