My name is Sofia Diniz, and I’m an undergraduate student majoring in Information Systems, set to graduate in April. I first became acquainted with iOS development as a student at the Apple Developer Academy in 2022. Two years later, I graduated from the Academy and began teaching iOS development there. Last July, I shifted my focus to building projects for the Vision Pro.
Along the way, I’ve won the Swift Student Challenge twice, developed various apps, published an article on leveraging component packages to improve accessibility in mobile apps, and deepened my interest in the Swift ecosystem, going beyond app development.
For the past few months, I’ve been eager to contribute to the ecosystem of open-source Swift projects. Since this will be my first open-source contribution, GSoC seems like the perfect opportunity to receive guidance while giving back to a community that has taught me so much.
I’m particularly interested in enhancing Swift DocC’s experimental documentation coverage feature and have been familiarizing myself with the codebase. So far, I’ve dived into related topics in the forum, cloned and run the repository and I am now diving into the documentation while evaluating potential first issues. I noticed that the tagged good first issues have been open for some time (with the latest comments dating back at least a year), so I was wondering if they are still relevant additions to the project.
As previously mentioned, I’m quite novice to this process, so my plan is to start with a good first issue, gain a deeper understanding of the codebase, draft potential implementations for my GSoC proposal, validate them if possible, and then finalize my proposal.
If you have any recommendations or suggestions on how to approach this process, I would greatly appreciate your guidance!
I'm happy to hear that you're interested in enhancing Swift DocC’s experimental documentation coverage feature.
I just had a look and those issues are all still relevant. We haven't added any new good first issue items in a while but if there's any particular area of the project that you're interested in I'm sure that we can find some new good first issues in that area as well.
That sounds like a good approach. I would also recommend playing around with the feature as it exists today to get a sense of how it behaves today and what data it output and compare that to how you'd expect it to behave and the data you'd expect it to output.
It could also be useful to prototype something (a website, app, or anything else that you're comfortable with) that displays some coverage data to build your own opinion on the current format—if it contains the information that you need, if it's easy to work with, etc.—and if there are any changes to the data that you'd like to propose to make it easier to present the information.
(That prototype isn't the end product of the project but it can be a relevant tool throughout your project to verify that the data is easy to work with and contains relevant information.)
Thank you for your kind and detailed reply! I really appreciate the guidance.
I noticed that you recently added a few new good first issues, and this one in particular caught my interest. However, it seems like someone else is already working on it, so I assume it would be best for me to explore other options.
These pointers were really helpful—thank you. I’ve tested the feature a couple of times already and have been taking notes on thoughts on how to improve it, particularly regarding the presentation of the data. I think this will create a good foundation for the prototype that you suggested.
I’ve also been reading forum posts about this feature in order to try and better understand it. These posts in particular gave me a some valuable insights:
Additionally, I’ve been reading deeper into the codebase, and from what I gathered (please feel free to correct me if I’m mistaken), most of the implementation of the Documentation Coverage feature spans across the following files:
Finally, I took another look into the open issues in the GitHub repository and came across this one. It seems to be a relatively simple fix, and it’s closely related to the area I want to focus on, so I believe it would be a fitting first dive into the codebase.
I would greatly appreciate hearing your thoughts on these matters :)
Yes, someone has expressed interest in working on that. I'll see if we can find another new good first issue in the same area for you.
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.
DocumentationCoverageOptions is the model for the command line options that the developer passes to docc convert. That would be a good place to add and/or remove command line flags and options based on what configuration you feel like is useful for the developer to be able to make for the coverage feature.
The code in DocumentationContext+Configuration is for making configuration to the context before it's created. Specifically, configuring shouldStoreManuallyCuratedReferences makes the DocumentationContext store curated references in manuallyCuratedReferences which the coverage data checks and reports on. If you need to make other coverage specific configuration changes to the documentation context, you can add values in Configuration.ExperimentalCoverageConfiguration and read them from the context.
While the thread is a few years old and some points may no longer be relevant, there could still be valuable insights to consider when planning future enhancements to this tool.
Thanks again for your interest, looking forward to your proposal :)