search

magefile / mage

a Make/rake-like dev tool using Go
https://magefile.org
Apache License 2.0
4.01k stars 250 forks source link

doc: consider altering // mage:import documentation to remove leading space #406

Closed efd6 closed 2 years ago

efd6 commented 2 years ago

The "mage:import" directive comment looks very much like it falls in the family of directive comments used by the compiler and other tools, for example linters (see golang/go#43776).

However it specifies in the documentation that a leading space should be included. The code specifically does not require this, so I would like to suggest that the documentation be changed to exclude the space.

This would have no backward incompatibility issues due to the current acceptance of the no-space variant, but over time would allow the Go community to converge on a consensus approach to using directive comments.

natefinch commented 2 years ago

This is a good point. I think changing the recommendation is probably a good idea.

efd6 commented 2 years ago

There is also the issue of the move to bug resistant build tags which should be finalised by 1.18 according to the issue. I will send a PR in two commit, the first handling the original issue and the second adjusting docs for the //go:build tags, but leaving ~all the code alone, I can back out the second commit if you don't want it.