DocC uses a less strict evolution process than Swift itself—both in terms of the pitch/proposal format itself and in terms of the review process—but new features are generally:
- Talked about in the Swift Forum's before or early in the development of that feature
- Introduced as "experimental" to indicate that there may still be breaking changes.
- Gated behind an off-by-default feature flag, unless the feature requires an explicit action to use (for example new markup syntax).
I went through some past DocC pitches/proposals, and here's an non-exhaustive list (in no particular order) of example pitches/proposals from various people who both contribute to DocC frequently and people who are first time contributors:
- Document Extensions to External Types Using DocC
- Customizing the look and feel of Swift-DocC-Render
- Extending Swift-DocC to support Objective-C documentation
- Improving the presentation of overloaded symbols in Swift DocC
- Supporting row and column spanning in Swift-DocC Markdown tables
- [Pitch] Quick navigation in DocC Render
- Improving DocC Default Diagnostic Formatting
- Improving the presentation of Swift-DocC declarations
- Supporting more types of documentation with Swift-DocC
- Swift-DocC sidebar
- Clang support for Objective-C symbol graph generation
- Documenting source language specific parameters and return values
- Extending Swift-DocC Render JSON to support multi-language symbols
- Human readable alternative for DocC symbol link disambiguation
- Supporting different casing styles in auto-generated text
- ...
Sometimes these threads have a lot of activity, sometimes they don't.
Sometimes someone—either a regular attendee or a guest—suggest these pitches as a topic for a Documentation Workgroup meeting, sometimes they don't.
Sometimes these pitches already have a draft implementation to begin with, sometimes they don't.
Sometimes there are separate threads to introduce the idea and to pitch the feature, sometimes both are done in the same thread.
For DocC, there's not a formal review process where a proposal is accepted or not. Instead, the pitches are primarily a means to seek feedback on the feature and its design and to iterate and refine based on that feedback. To date, features typically aren't rejected unless there's significant outstanding feedback. In my view the lack of explicit approvals hasn't caused any issues for DocC so far, and I enjoy the low-overhead of it, but I can also see potential flaws with it. If someone feels that the evolution of DocC would benefit from more formal process, it would be a good topic for a future Documentation Workgroup meeting. These meetings are open to anyone who is interested are usually held every two weeks; announced via a forum post in the Swift Documentation / Workgroup Updates category. For more information, contact @swift-documentation-workgroup.
Even with an iterated-upon and refined design, someone has to implement it. People are often very busy with their own projects and other responsibilities but many people are also happy to help out, answer questions, or mentor anyone who wants to contribute.
Depending on the amount of initial feedback and design refinement, features are generally introduced as "experimental" to indicate that there may still be breaking changes.
Merging experimental—or otherwise in-progress but usable—features can be a valuable tool to gather feedback from a broader group of people or to gather feedback based on actual usage. The number of people who are interested and have spare time to build a branch of Swift-DocC from source to try out a feature and run it with their real world project's data is very small.
Sometimes this additional feedback from people who use a feature in its experimental state help help refine the design, sometimes it helps verify the design, and sometimes it does neither and potential questions about the feature's design remain unanswered.
As far as I personally know, no one is already working on documentation coverage or anything related that would supersede it or otherwise make an effort into improving documentation coverage go to waste.
If you want to work on the pitch (and/or implementation) to make documentation coverage a non-experimental feature I'd be happy to help with that. We could either use this thread for that discussion or start a new thread about it.
I will say that there are a few aspects of documentation coverage that I personally would like to see revisited—while breaking changes are still accepted—before removing it's "experimental status":
- The output format. Specifically, I'd love to have a discussion about:
- what information would be useful to include so that other tools can read and present the coverage information
- how the format could be structured so that new coverage metrics could be added and displayed without requiring further changes by those tools.
- The command line options. Specifically; I think it would be a good opportunity to talk about:
- Is
--coverage-symbol-kind-filter <symbol-kind>option (to only emitting coverage data about a certain kind of symbol (for example enumerations but not classes) useful? - Are there other flags or options that would be useful to have? For example; would it be useful to only emitting coverage data for a certain sub-hierarchy or to only emit certain coverage metrics?
- Is