x/sys/windows: godoc is useless again

[bradfitz]

The godoc for https://godoc.org/golang.org/x/sys/windows is empty, probably because of https://go-review.googlesource.com/24952

Maybe this is a gddo problem too. (Or maybe gddo can help or have better heuristics over which build context to use)

/cc @alexbrainman @adg @broady @shantuo @alandonovan

[alexbrainman]

Unfortunately I don't have any bright ideas.

I am sure it is because of CL 24952. I can revert the change. But then we need to find different solution to issue #16368.

Alternatively we can hard code golang.org/sys/windows (and some others) in gddo to display these as windows packages. But this is very error prone. And what about other similar packages?

Maybe we could come up with some new gddo rule for that. Compare different GOOS / GOARCH versions of the package - number of global variables, functions, types and so on - and show version with most of these.

What do you think?

Alex

[broady]

Maybe, until godoc can recognize build tags, we need a special build tag for godoc.

//+build godoc to force godoc for a file.

It's ugly, but is it bad?

[bradfitz]

1. The quickest easy fix is hard-coding specific packages (this one) to use a different build context. We could to that immediately while we do the next step:

2. Try Linux/amd64 build context first. If it yields any exported symbols at all, stop and use it. If it's totally blank, then do a more intensive scan looking for which build context is best.

[minux]

I still think making go generate recognize GOOS/GOARCH is wrong. go generate is different from build, so it shouldn't take build tags into account.

[alexbrainman]

1. The quickest easy fix is hard-coding specific packages (this one) to use a different build context. ...

Like this https://go-review.googlesource.com/#/c/25353 ?

Alex

[gopherbot]

CL https://golang.org/cl/25353 mentions this issue.

[coelho]

Underlying cause makes Windows development more difficult as both godoc & pkg.go.dev miss exported functions of some packages due to Windows build constraints.

Example:
https://godoc.org/github.com/microsoft/go-winio
https://pkg.go.dev/github.com/microsoft/go-winio
Missing "DialPipe" defined in "pipe.go" with the +build windows constraint (as well as many more...)

I don't think it is go doc's responsibility to enforce build constraints & if anything it should say somewhere in the documentation that a function is only exported on a certain OS/ARCH if that is the case.