x/pkgsite: docs not shown for functions with language version build tags

[destel]

What is the URL of the page with the issue?

https://pkg.go.dev/github.com/destel/rill@v0.4.0#pkg-functions

What is your user agent?

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36

Screenshot

No response

What did you do?

I updated my Go library to include new functions that use Go 1.23 features (iterators), while maintaining compatibility with Go 1.20. So, I put several functions into a separate file and added a build constraint to that file.

So, my setup is:

• go.mod is 1.20
• file iter.go has //go:build go1.23
• other files do not have build constraints

What did you see happen?

• There is no documentation for the functions from iter.go file on https://pkg.go.dev
• At the same time, when I run pkgsite locally it correctly shows documentation for all functions

What did you expect to see?

Expected to see documentation for all functions from all files

[gabyhelp]

Related Issues and Documentation

• x/pkgsite: package docs missing for packages that use "//go:build" without "// +build" #49229 (closed)
• x/pkgsite: request for documentation for non-std modules responds with an error #51368 (closed)
• x/pkgsite: support showing identifiers that are constrained by build tags #45833 (closed)
• x/pkgsite: `main` package symbols aren't documented: "There is no documentation for this package" #65731 (closed)
• x/pkgsite: provide documentation for older, still supported go versions #65012 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[codyoss]

Just to inline some comments I had filed in a separate, now closed issue:

I expect users of the library to be able to see docs for all Go versions or have the ability to select a Go version to see the docs of.

As a library maintainer it is important to me to maintain broad support for versions of Go. But it is also important for me to be able to implement and share new language features like iterator support gated by build tags.

For standard library packages it seems you can see all supported symbols, and it even lets you know when things were added. Example: https://pkg.go.dev/net/http#Request.PathValue

[ansaba]

cc: @jba

[jba]

Unfortunately it's too expensive for pkgsite to generate docs for files with build tags. We do handle a few GOOS/GOARCH configs, but that's it. In general the number of possibilities is exponential so it's infeasible.
Maybe we should handle language version tags.
On the other hand, since pkgsite stores the source in the background and generates docs on the fly, we probably could support this if we stored all the source.

[codyoss]

Yeah, I could see how general build tags could be problematic. My personal ask here would just be for language versions. And/Or docs assume the latest go version to show all possible methods?!

[destel]

@jba, thank you for the response.

Is there an official way to have some functions of a library to be Go 1.23+ only, while being properly documented. Maybe not build tags, but something else?

Another thing that's not clear to me: when I run pkgsite on my machine, it properly shows docs for all functions regardless of build tags.

[destel]

Also, It seems I've noticed a potentially relevant change:
golang/pkgsite@a03e71d

This 2-days-old commit seems to upgrade the Go version from 1.22 to 1.23. I'm not sure if it's related to the issue we're discussing, but I thought it might be worth mentioning. For context, I encountered a documentation issue 4 days ago.

I'm not familiar with pkgsite's source code yet, so I'm just speculating.

[jba]

You're right, the upgrade to 1.23 would result in the new functions being shown. I just had to reprocess your existing module and now you can see them: https://pkg.go.dev/github.com/destel/rill@v0.4.0. Anything you publish in the future will have 1.23 symbols too.

That is also why it shows them on your machine: you are running go 1.23.

Obviously this is not the complete solution that @codyoss and others would like, where you can, say, select a Go version from a dropdown and see the symbols defined for that version. That could be filed as a feature request, but to be honest, I don't see it happening any time soon because it's a relatively rare request and would require a fair amount of work on both the frontend and backend.

I'm going to close this, since it's a bug report and the "bug" is fixed.

[destel]

@jba Thank you very much.
Is it also possible to delete two versions of my lib from pkg.go.dev?
v0.4.1-debug1 - I created it in an attempt to fix the issue with go.mod changes
v0.1.1-debug1 - older debug version from the times when I didn't know there was no simple way to delete versions

[jba]

We can't remove individual versions, only entire module paths.
The best you can do is retract them. We then display that on the doc page:

and on the versions list:

[destel]

Thank you. I'll try that