Hi,
There's a fair amount of information missing from this post that makes it difficult to have a meaningful discussion about the proposed changes.
This message briefly summarizes the evolution process for DocC and links to several pitches/proposals—from both people who contribute to DocC frequently and people who are first time contributors—that you can use as inspiration when writing your own pitch/proposal.
At this stage, the implementation is less relevant. Instead, it would be good to focus the discussion on:
- What problem statement this proposal is looking to solve.
- A brief high-level recap of the current implementation so that people have enough background to participate in the technical discussion about it.
- How proposed solution solves that problem
- Details, at a high level, about what component is responsible for finding and parsing the snippets both inside the catalog and outside the catalog.
- Any plans for the existing snippet-extract tool and its integration with the Swift-DocC Plugin.
- Any restrictions around which paths outside the catalog that is allowed to be referenced and which aren't (for example: only files within the package/repo) and what component is responsible for validating those paths.
- A brief description of one or more viable alternatives and why the proposed solution solves the stated problem better than those alternatives. Here it would be good to describe an alternative where the Swift-DocC Plugin continues to be responsible for finding and parsing the snippets.
- It would be good to compare the proposed solution and the alternatives on how they can be extended in the future. For example, currently, when DocC is passed snippet information in symbol graph files, any tool or custom script could create a symbol graph file for snippets in any language and DocC would be able to display them.
- Any open questions that need to be discussed where the pitch/proposal doesn't make a specific recommendation.
Please update your proposal to have a short section for each of those topics so that it's easier for the community to discuss the proposal.