syscall: improve NewCallback documentation and panic message

[aclements]

What version of Go are you using (go version)?

Tip (commit 65d55a1)

Does this issue reproduce with the latest release?

Yes.

syscall.NewCallback (and syscall.NewCallbackCDecl) don't describe what's expected of the type of their argument beyond "it must be a function". But they do have requirements. For example, if you pass a function with no argument and no results, they panic with "compileCallback: function must have one output parameter". I don't actually know what this means a priori, and the NewCallback documentation doesn't tell me. The term "output parameter" doesn't appear in the Go spec, and it could (and does in this case) mean a result value, or it could mean a C-style output parameter which is actually an input argument that points to where to put the result.

We should document NewCallback*'s requirements and clarify the panic message for when they're violated.

/cc @alexbrainman

[aclements]

Ah, "output parameter" appears in the reflect documentation, which is probably where this terminology came from. That may be a bug in the reflect package documentation. :)

[alexbrainman]

@aclements I totally agree. syscall.NewCallback documentation is bad.

syscall.NewCallback was used to allow for calling WindowProc ( https://msdn.microsoft.com/en-us/library/windows/desktop/ms633573(v=vs.85).aspx ) and service handler ( https://docs.microsoft.com/en-us/windows/desktop/api/winsvc/nc-winsvc-lphandler_function_ex ).

Alex

[jeet-parekh]

I could help with this. The documentation has to be updated in x/sys or syscall?

[alexbrainman]

I could help with this.

Please, do.

The documentation has to be updated in x/sys or syscall?

Both. I suggest you create CL for syscall first. And then we could copy it to x/sys.

Thank you.

Alex

[gopherbot]

Change https://golang.org/cl/126035 mentions this issue: syscall: improve NewCallback documentation and panic message