More readable package and long help comment rendering

[jonasrmichel]

Currently, the package comments displayed with mage -l and "long help" comments displayed with mage -h <target> are rendered on a single line.

Sometimes more info needs to be provided in these comments than can comfortably fit on a single line. With too much text the result is a long block that is not too human friendly.

As an aside, there's a dirty hack for the mage -l package comment. Line breaks can be injected like so:

// +build mage

// First line
// `+"\n"+`
// Second line
package main

The hack only works for the mage -l package comment rendering, and not for the mage -h <target> long help.

Ideas

To allow for more readable rendering of long blocks of help text, perhaps one or both of the following approaches could be taken.

Commented lines with only white space result in a line break in the rendered text.

// +build mage

// First line
//
// Second line
package main

Block comments are rendered verbatim.

// +build mage

/*
First line
Second line
*/
package main

[natefinch]

Sorry, I thought I replied to this but maybe never sent it. I actually made comments explicitly not wrapped so that things wrap according to the terminal width. I did that because I was getting some weird behavior from otherwise normal looking comments. But you may be right in that the code wrapping should be respected. I'll think about it.

[bobhenkel]

I would like this for long help as well. It would be nice to beable to describe a task and get long help like this.

mage --help
mage [options] [target]

Mage is a make-like command runner.  See https://magefile.org for full docs.

Commands:
  -clean    clean out old generated binaries from CACHE_DIR
  -compile <string>
            output a static binary to the given path
  -init     create a starting template if no mage files exist
  -l        list mage targets in this directory
  -h        show this help
  -version  show version info for the mage binary

This is an example, I know mage tasks don't take option flags. This could help describe what parameters the task should take in and what env variables or config values to set for them.

[ladydascalie]

I'd like to revive this issue. I think this has gotten even more important now since Mage targets can accept parameters.

One example of a target I am working with is as follows:

My target has this signature

func HMACSignature(jsonString string) error {}

It's usage looks like this:

mage hmacSignature '{
        "foo": "bar",
        "baz": "qux"
}'

I would love to document this use in a way that is readable in the command line:

// HMACSignature allows creating a new signature for the given json payload.
// This target allows [some internal business I'm not pasting here].
//
// Example:
//
// mage hmacSignature '{
//        "foo": "bar",
//        "baz": "qux"
// }'

I would like to say I'm also happy to help on this, if I can be suggested where to start looking.