build.Doc() doesn't play well with multi-line doc strings.

[vsivsi]

Attempt A:

For example:

TEXT("add", NOSPLIT, "func(x, y uint64) uint64")
Doc("add uint64 x and y\nreturns uint64 sum of x and y")

Produces invalid syntax:

// add uint64 x and y
returns uint64 sum of x and y
func add(x uint64, y uint64) uint64

Attempt B:

Using Doc multiple times...

TEXT("add", NOSPLIT, "func(x, y uint64) uint64")
Doc("add uint64 x and y")
Doc("returns uint64 sum of x and y")

... doesn't work as expected:

// returns uint64 sum of x and y
func add(x uint64, y uint64) uint64

Attempt C:

Just writing a really long docstring...

TEXT("add", NOSPLIT, "func(x, y uint64) uint64")
Doc("add uint64 x and y returns uint64 sum of x and y which is super useful when you just want to add two numbers with a whole bunch of call overhead as an excuse to use Avo")

...doesn't result in a sensibly wrapped output:

// add uint64 x and y returns uint64 sum of x and y which is super useful when you just want to add two numbers with a whole bunch of call overhead as an excuse to use Avo
func add(x uint64, y uint64) uint64

Suggestion:

Cases A and B are arguably bugs. Case C would be nice to fix, but is probably not needed if A and B are fixed.

[vsivsi]

I hasten to add: yes, I know that Doc() is variadic, and using it that way is the "correct" way to address the use cases above. But attempts A-C above are not unreasonable things for a user to try, and they all fail in their own way to generate the predicted output.

[mmcloughlin]

Hmmm, yes agree A and B are not ideal. I could change Doc to append. I find it hard to believe anyone would be relying on the existing overwrite behavior.

Not sure about auto-wrapping, it's not always what you'd want. Maybe a different function like WrapDoc? Is there a better name?

[vsivsi]

I'm not that enthusiastic about auto-wrapping, agree that's really on the coder to auto wrap if they want.

Note that Comment and Commentf also suffer from case A:

TEXT("add", NOSPLIT, "func(x, y uint64) uint64")
Doc("add adds x and y.")
Comment("This belongs on\n multiple lines")

In asm output:

// func add(x uint64, y uint64) uint64
TEXT ·add(SB), NOSPLIT, $0-24
	// This belongs on
 multiple lines
	MOVQ x+0(FP), AX