I see two problems here, and one of them is definitely a mage bug. Mage scrapes the go doc for the function. If you run go doc for a function with those comments, it will look the same. Go doc doesn't respect single line returns. When I've had to write docs like that, I've had to use double spaces at the beginning of each newline to tell go doc that this part of the docs are pre-formatted.

So if you do this, go doc will look right:

// Start creates and starts a new MongoDB container using the specified params.
// With the exception of name, all params can use defaults by using "-" for each.
// Params:
//  - name         required
//  - version      optional  default 4.4
//  - network      optional  default no network
//  - hostPort     optional  default 27017
//  - replicatSet  optional  default no rs
//  - templateFile optional  default no template restored
func Start(name, version, network, hostPort, replicaSet, templateFile string) error {

(note there are two spaces before each dash)

However, even doing that does not produce good output with mage.

This will take a little looking into. I think we had stripped out line returns on the assumption that the terminal would wrap it for you.... but that's not the right thing to do for preformatted stuff like this.

If go doc writes the right thing (which it seems to), we might be able to just steal that text directly.

Wouldn't this be solved by just removing the following call to toOneLine ?

Is this something else that I'm missing on why that's needed @natefinch? It makes sense to convert comments into one-liners for targets help messages, but not for the package comment.

Edit: I've opened a PR #459 that resolves this issue with the approach described above.

Hmm. I had problems with keeping the original newlines, because the width of your editor window might be wider than your terminal window... And while the editor will scroll off the right side with a horizontal scrollbar, the terminal just wraps it and makes it super ugly.

It's not great. It would definitely be better to have some middle ground that could preserve lone returns without messing up all the formatting from ugly line wraps.

Formatting in the terminal is always a tricky problem, but I think that whatever go doc does should be good enough for this project. In fact, I think this tool should behave exactly the same, and I've updated my PR to mimic this behaviour using: https://pkg.go.dev/go/doc#Package.Text instead of the raw doc string.

Ugly terminal wraps in widths smaller than 80 characters sucks, but the current behaviour of mixing everything in just one line it's worse, specially with current decade wide & ultra-wide high-res monitors.