I noticed that the "Man page" tab of the "ArgumentParser in use" section of the Swift.org page contains an error. This is important because this page should be perfect. It is Swift's "hello world".
If you copy the content of the "Man page" tab, paste it in a file, and open the file with man, you see this:
The last two lines before EXIT STATUS should not be there. Repeat has no subcommands.
[I] release> ./repeat -h
USAGE: repeat [--count <count>] [--include-counter] <phrase>
ARGUMENTS:
<phrase> The phrase to repeat.
OPTIONS:
--count <count> How many times to repeat 'phrase'.
--include-counter Include a counter with each repetition.
-h, --help Show help information.
Also, it appears that the JSON output has a corresponding error. (Perhaps this is why the man page is bad).
I made a separate package for SAP's repeat example and ran swift package generate-manual to see if this had been fixed. It's still a bug:
[I] repeat> cat ./repeat.1
.\" "Generated by swift-argument-parser"
.Dd February 21, 2026
.Dt REPEAT 1
.Os
.Sh NAME
.Nm repeat
.Sh SYNOPSIS
.Nm
.Ar subcommand
.Op Fl -count Ar count
.Op Fl -include-counter
.Ar phrase
.Op Fl -help
.Sh DESCRIPTION
.Bl -tag -width 6n
.It Fl -count Ar count
How many times to repeat 'phrase'.
.It Fl -include-counter
Include a counter with each repetition.
.It Ar phrase
The phrase to repeat.
.It Fl h , -help
Show help information.
.It Em help
Show subcommand help information.
.Bl -tag -width 6n
.It Ar subcommands...
.El
.El
.Sh "EXIT STATUS"
.Ex -std⏎
Have you filed an issue with the repository? This is great detail, and that's the ideal place to capture it. Sounds like this even might be a great "good first issue" kind of report.
That "subcommands..." field is the argument to the built-in mycommand help subcommand.
This is a place where I haven't been happy with the current man generation, and what you're seeing is "working as intended" where what should be intended is up for debate .
Another thing I haven't been happy with is that we emit -h --help and --version at every level of the command hierarchy in the man page.
If you have a better idea on how the man page should represent this, i'm fairly confident implementing it should be straightforward.
Interesting - I didn't know that the repeat example provided by SAP had a built-in help command. But then again, the ParsableCommand protocol has a plethora of features. That
said, I ran the following, and contrary to what the generated man page said, this did not show help info:
[I] release> ./repeat help
help
help
IMO, there is no room for debate. That help line should not be there. If you insist, then the help screen should also show a help command. The help screen and manual page should not contradict each other.
Here I would suggest leaving the first line and dropping the last three. The last three are incorrect because they suggests that help has subcommands and that help has a version flag.
As an aside, personally, I greatly prefer multi-page because the hierarchy can get really messy, especially if you have a lot of text in the description sections, or have example sections, etc. If all you have is list of the options - then fine.
Multi-page
Here is the top level in muti-page mode. It looks really good.
I would, however, suggest that you show the subcommands, with a short description somewhere on the man page. (I would keep the SEE ALSO section as is). E.g., like the help screen.
[I] release> ./math --help
OVERVIEW: A utility for performing maths.
USAGE: math <subcommand>
OPTIONS:
--version Show the version.
-h, --help Show help information.
SUBCOMMANDS:
add (default) Print the sum of the values.
multiply, mul Print the product of the values.
stats Calculate descriptive statistics.
See 'math help <subcommand>' for detailed help.
The man page should just say what the tool does. If the tool, line SAP's math example, has --help and --version at each level. the so should the man page. If it doesn't (i.e., version string is empty in the configuration at given level)
, then neither should the man page. As far as I can tell you have this just right already.
.
