Repository navigation
Option -h doesn't respect comment newlines. #358
Description
Given the following target (imported into main magefile):
// 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 {The following is the output of -h:
$ mage -h mongo:start
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 - replicaSet optional default no rs - templateFile optional default no template restored
Usage:
mage mongo:start <name> <version> <network> <hostPort> <replicaSet> <templateFile>
Expected behavior would be to print the comments with their newlines as written in the comments describing the imported target, like so:
$ mage -h mongo:start
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
- replicaSet optional default no rs
- templateFile optional default no template restored
Usage:
mage mongo:start <name> <version> <network> <hostPort> <replicaSet> <templateFile>
Activity
natefinch commentedon Sep 24, 2021
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 docfor 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 docwill look right:(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.
pablojimpas commentedon Mar 1, 2023
Wouldn't this be solved by just removing the following call to
toOneLine?mage/parse/parse.go
Line 250 in 02bde0b
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.
Respect newlines in package comments
natefinch commentedon Mar 2, 2023
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.
pablojimpas commentedon Mar 2, 2023
Formatting in the terminal is always a tricky problem, but I think that whatever
go docdoes 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.
Respect newlines in package comments
Respect newlines in package comments
Respect newlines in package comments