I’m interested in the GSoC project idea “Improved documentation for command line tools” (Swift Argument Parser plugin + symbol graph + DocC). I plan to submit a proposal and would appreciate some guidance from mentors and the community.
I’ve read the existing discussion ([GSoC 2025] Improved command line tool documentation), including the scope around richer markdown vs. symbol graph generation and the option to prototype DocC enhancements that use the command symbol graph. I’d like to align my proposal with what’s feasible and most useful.
Could you share:
Any updated priorities or constraints for this project?
Suggestions for scoping (e.g. starting with markdown/plugin improvements vs. symbol graph first)?
Whether it would help to share a draft proposal here for feedback before the deadline?
I wanted to check if the following direction makes sense for the first phase of the project (richer markdown and configuration).
My plan is to group each command’s arguments into clear sections in the generated markdown, similar to how the CLI –-help output is structured.
if option groups are defined, I’ll reuse those so arguments appear under the same section titles as in the help text.
if no grouping is defined, I’d go to default sections like Arguments, Options, Flags, and Subcommands to keep the documentation consistent and readable.
Implementation plan i have is to make small PRs. first implement sectioning and grouping, second adding default/ allowed values to the markup, and 3rd possibly add more plugin configuration options
Does this align with what you had in mind for the “richer markdown and config” part, or would you prioritize something else first?
Happy to adjust the plan based on your feedback before locking it into the proposal.
this approach seems good to me, but the potential mentor mentioned on the site will give better opinions. you should share your complete proposal for review that will be better
Thank you, I appreciate it. Even a small suggestion or correction means a lot, I really think I have a good plan for this project idea, I basically love making UI better. And command is something that I use everyday.
On the tooling side, there haven't been any significant changes since the discussions from last year. I'm only aware of a few small tweaks to the markdown output.
So, while the priority of this project idea is largely the same as last year, there is now a key tool in the Swift ecosystem that publishes documentation about its command line interface based on this output. This means that any improvements that you do would be reflected on those pages.
My recommendations specifically for scoping a project like this—where there isn't a single larger feature or enhancement to implement—would be to pick and choose a combination of different improvements that you each think provide some value in a way that also makes sense, or "tell a cohesive story", in aggregate.
That has the benefit that you can more easily make incremental improvements and that it's easier to rescope if you find that it's going either faster or slower than what you initially expected/planned.
If you think about the benefits that you want to accomplish and work your way backwards to how to accomplish that then this can also make it easier to write up a proposal because you'll have more concrete goals to write about.
Another aspect to consider is your own learning for example by asking yourself "what do I want to have learnt after this?". Being aware of what you want to learn can help you identify which improvements you would find most motivating to work on and influence your pick of improvements.
One way to go about making this a bit more concrete—to have somewhere to start—could be to look at of the Swift Package command pages (for example the add-dependency subcommand and compare that to the corresponding help text. From this you can both note a number of differences; to name a few:
the page lists a large number of flags that the help text doesn't
the pages doesn't separate arguments and options into groups
flags like --type neither display their possible/allow values nor the default value
and you can try to ask yourself the question "what would I want to improve about this page"
Unfortunately that specific command doesn't organize its arguments and options into named groups so it can be useful to look at other tools and other commands as well to get a broader picture of the current state of the output and the possible improvements.
When it comes to knowing what improvements can be made in
the markdown alone
the markdown with generic symbol data
the markdown with custom symbol data
my top recommendation would be to ask if you're unsure.
For changes that you think could or couldn't be made to the markdown output alone you can also experiment by editing the markdown by hand and seeing how it renders. For example; you can include the --type options's possible/allowed values and its default value as text somewhere in its description and see if you find a location and formatting that you like.
For the differences between what could be accomplished with generic symbol data compared to custom symbol data I recently listed a few examples (in this post) about some of the things that structure symbol data could do for command line documentation.
If you have any questions about that or anything else, don't hesitate to ask.
Yes, if you can share a draft and get feedback on it that allows you to iterate on your proposal before submitting it.
I’ve created an initial version of my GSoC proposal for the “Improved Documentation for Command Line Tools” idea. It’s still a rough draft, and I’m sharing it mainly to get feedback on the overall approach and technical direction.
One thing I want to mention is that the timeline might not be optimal yet. I’m still learning how work is usually structured and reviewed in large Swift and Apple ecosystem projects. I expect that part to improve as I receive feedback. For now, my main goal is to confirm whether the implementation approach makes sense, especially the steps about improving the Markdown generation first and then adding a supplementary symbol graph for DocC.
I also haven’t built a prototype yet, so the proposal doesn’t have screenshots of generated documentation. I wanted to first confirm that the direction is reasonable before spending time building those examples. If anyone has time to take a look, I would really appreciate any feedback or criticism, especially from @ronnqvist.
Thanks for the detailed guidance. I’m still working through your suggestions, in particular, the SwiftPM add-dependency comparison and thinking about which improvements to pick and how to scope them.
I’ll complete and share an updated proposal once I’ve done that. but please take a look at the current approach.
I really like the usage of diagram, but creating the prototype for screenshot really necessary? you can just create codeblocks right? and you and merge some of the weeks to tighten the timeline table
thank you, i actually have been working on the diagram because it gives the idea how brainstorming will be directed. I have seen previous year proposals and may have added there prototype, i think i will make the sample anyways so codeblocks will not be needed.
the timeline will be my next priority after confirming the approach