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

Comment From: gabyhelp

Related Issues and Documentation

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

Comment From: 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

Comment From: ansaba

cc: @jba

Comment From: 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.

Comment From: 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?!

Comment From: 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.

Comment From: destel

Also, It seems I've noticed a potentially relevant change: https://github.com/golang/pkgsite/commit/a03e71dcf0d6565c0d4c7828d8b3875801e43f1a

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.

Comment From: 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.

Comment From: 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

Comment From: 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: Golang x/pkgsite: docs not shown for functions with language version build tags

and on the versions list:

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

Comment From: destel

Thank you. I'll try that