support for inline doc comments on optional flags

[natefinch]

e.g.

// Deploy runs the build and then uploads the artifacts to the server.
// It deploys to the given environment.
func Deploy(ctx context.Context, env string, 
    version *string, // git tag for the build, defaults to the next minor build if not set 
    dryRun *bool,    // if set to true, just outputs the build artifacts 
    ) error {
    return nil
}

$ mage -h deploy
Deploy runs the build and then uploads the artifacts to the server.
It deploys to the given environment.

Usage:

	mage deploy <env> [<flags>]

Flags:

    -version=<string>  git tag for the build, defaults to the next minor build if not set
    -dryrun=<bool>     if set to true, just outputs the build artifacts

[Copilot]

Pull request overview

This PR adds support for showing inline (trailing) parameter comments as documentation for optional flag arguments in mage -h <target> output, including a new Flags: section when appropriate.

Changes:

• Extend parsed function argument metadata to carry an optional inline comment and render it in help output.
• Update parsing to preserve and/or recover inline parameter comments from Go source.
• Update docs and add tests covering multi-flag and single-flag documented help output.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
site/content/targets/_index.en.md	Updates documentation to demonstrate inline flag doc comments and new help output format.
parse/testdata/optargs.go	Adds a test fixture function with inline comments on optional parameters.
parse/parse_test.go	Extends optional-args parsing tests to assert captured inline comments.
parse/parse.go	Adds Arg.Comment, computes whether to show a Flags: section, formats flag docs, and attempts to extract inline param comments.
mage/testdata/optargs/magefile.go	Adds magefile targets used by help-output tests for documented flags.
mage/template.go	Updates help template to emit [<flags>] usage and optional Flags: section.
mage/args_test.go	Adds assertions for new help output that includes Flags: and inline flag documentation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.