Enhance DocC-compatible inline docs for future documentation (Issue #866)

[RintaroYamada]

Summary

This PR enhances inline documentation within mas commands using DocC-compatible comments (///, CommandConfiguration.abstract, @Argument(help:), etc.).

The goal is to lay the foundation for proper DocC and manpage generation in the future.

Context

• Initially attempted to use Swift Argument Parser's generate-docc-reference, and confirmed it works.
• However, due to internal visibility and lack of .docc markdown files, detailed documentation does not yet appear in preview.
• As a future direction, I plan to create .md files under mas.docc (e.g., install.md, list.md) to generate a full-featured DocC website.

Notes

• This PR does not include manpage customization (Issue Generate man pages with SAP #865).
• The enhancements are primarily for Issue Generate web documentation with SAP #866 (DocC generation).
• If the inline comments are considered too verbose, I can revise them or remove as needed.

Thank you for maintaining this project!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[rgoldberg]

@RintaroYamada Thanks for starting this.

I've quickly looked over this PR while on my phone, so if I misunderstood something, please let me know.

Background

The documentation in the DocC comments does not appear to have been included in the generated Markdown file, which is expected because, IIUC, the plugin reads the documentation from SAP constructs (like CommandConfiguration.abstract, @Argument(help:), etc.; there might be other SAP constructs, like description, details, etc. that also might be more appropriate for various parts of the docs), not from DocC comments (///).

I think the DocC confusion might stem from the plugin using DocC formatted input from the aforementioned SAP constructs, not DocC formatted input from DocC comments.

The documentation should also be removed from README.md so that we needn't maintain two copies of it. It should be copied from the SAP constructs to the generated Markdown file.

TL;DR

Thus, can you move the docs from the DocC comments into SAP constructs (after researching how the various SAP construct options for generating docs)?

Instead of leaving the commit where the docs are in the comments in the PR branch, please rebase your new version on main, so the docs go straight into the SAP constructs, rather than detouring through the DocC comments.

Thanks again.

[RintaroYamada]

@rgoldberg
I've noticed that the man page format merges the abstract and discussion into a single section, while the autogenerated mas.md splits them more structurally.
Because of that, we're aiming to simplify the discussion field to be plain-text-like, without Markdown icons, formatting, or excessive length. This helps the man page remain clean and consistent across commands.
Just letting you know in case this affects future documentation conventions or guidance!

[rgoldberg]

@RintaroYamada Thanks for the heads up.

This open PR for SAP from someone else, not from me, is to improve the Markdown generation plugin (it might eventually also update the man page generation plugin). You might want to see if it will change what you'll want to do for mas.

A completely separate question: what are you using to work on mas? i.e.: what version of macOS, Xcode, Xcode Command-Line Tools, and anything else that might be relevant are you using?

Are you able to build mas in Xcode? I was previously able to build older versions of mas in Xcode 14.2 on macOS 12.7.6 on Intel, but neither those same versions of mas, nor newer versions of mas, will build for me in Xcode 16.4 on macOS 15.5 on an M4 (nor in Xcode 16.3 before I upgraded to 16.4). Obviously, Scripts/generate_package_swift (or the equivalent for older mas versions where the script was located at a different path) must be run before Xcode can build anything, but, otherwise, I cannot build in Xcode 16.4, so I cannot debug. (I normally code in the latest JetBrains IntelliJ IDEA Ultimatem because I'm used to it for other development). Thanks for any info you can provide.

[RintaroYamada]

Hi @rgoldberg,

Thanks for your message. Here's my current environment and build status:

Environment Information:

macOS:
Darwin 24.5.0 (Kernel: xnu-11417.121.6~2)
Architecture: x86_64 (Intel Mac)
Xcode:
Xcode 16.4 (Build 16F6)
Command Line Tools path: /Applications/Xcode.app/Contents/Developer
Swift:
Swift version 6.1.2
swift-driver version: 1.120.5
Target: x86_64-apple-macosx15.0
I’m working on mas using Xcode as my primary development environment.

I was able to successfully build mas using swift build on this setup.

The build output included a couple of minor warnings from dependencies (Quick and Nimble) about .xcprivacy files not being declared as resources:

warning: 'quick': found 1 file(s) which are unhandled; explicitly declare them as resources or exclude from the target
.../Quick/Sources/Quick/PrivacyInfo.xcprivacy
warning: 'nimble': found 1 file(s) which are unhandled; explicitly declare them as resources or exclude from the target
.../Nimble/Sources/Nimble/PrivacyInfo.xcprivacy
But overall, the build completed successfully:

Build complete! (6.89s)
Let me know if there’s anything else I can help test or verify!

[rgoldberg]

@RintaroYamada Thanks for the info.

Are you building from the command line using Scripts/build, swift build, xcodebuild, or something else?

Or are you building inside of Xcode itself? (Using the build action or any of its derivatives)

Have you ever been able to debug mas in Xcode?

I'm able to build from the command line using Scripts/build or swift build (& I can use all the other scripts in Scripts/ & any command lines using the swift command), but not using xcodebuild. I am not able to build inside Xcode using the build action, nor can I debug within Xcode. It worked on my old Mac running Xcode 14.2, though.

Thanks again.

[RintaroYamada]

Hi @rgoldberg,

Thanks for the follow-up.

To clarify:

I’ve been building mas using swift build directly from the command line (in the root directory).
I haven't used Scripts/build or xcodebuild.
Also, I haven’t tried building or debugging mas inside the Xcode app itself yet — I’ve only worked via the command line so far.
If needed, I can try building/debugging in Xcode to help investigate the issue.

Let me know what would be most helpful next!

[rgoldberg]

@RintaroYamada If you're building from the command line, it's easiest to use Scripts/build, so you don't need to separately run Scripts/generate_package_swift.

Getting debugging to work in Xcode 16.4 would be very useful. Maybe it will work immediately for you, or maybe you'd run into the same issue that I do or another issue when building to debug in Xcode 16.4.

Please let me know what happens when you try that.