Merge pull request NixOS#89372 from roman/88716/documentation-changes

gotools: update comments regarding gopls

pkgs/development/tools/gotools/default.nix

@@ -11,12 +11,16 @@ buildGoModule rec {
     sha256 = "0a8c7j4w784w441j3j3bh640vy1g6g214641qv485wyi0xj49anf";
   };
 
-  # Build of golang.org/x/tools/gopls fails with:
-  #   can't load package: package golang.org/x/tools/gopls: unknown import path "golang.org/x/tools/gopls": cannot find module providing package golang.org/x/tools/gopls
-  # That is most probably caused by golang.org/x/tools/gopls containing a separate Go module.
-  # In order to fix this, we simply remove the module.
-  # Note that build of golang.org/x/tools/cmd/gopls provides identical binary as golang.org/x/tools/gopls.
-  # See https://github.com/NixOS/nixpkgs/pull/64335.
+  # The gopls folder contains a Go submodule which causes a build failure.
+  # Given that, we can't have the gopls binary be part of the gotools
+  # derivation.
+  #
+  # The attribute "gopls" provides the gopls binary.
+  #
+  # Related
+  #
+  # * https://github.com/NixOS/nixpkgs/pull/85868
+  # * https://github.com/NixOS/nixpkgs/issues/88716
   postPatch = ''
     rm -rf gopls
   '';