Fix “deprecated” comments. (#4423)

A “deprecated” comment must be a separate paragraph, and there must be
at least one other paragraph in the docstring. Otherwise pkg.go.dev
won’t mark the symbol as deprecated.

**What type of PR is this?**

Documentation

**What does this PR do? Why is it needed?**

Correctly marks the deprecated symbols as deprecated on pkg.go.dev.

**Which issues(s) does this PR fix?**

Fixes #

**Other notes for review**

Author: phst

go/tools/bazel/bazel.go

@@ -24,10 +24,16 @@ import (
 	"os"
 )
 
+// The name of the environment variable to access test data files.
+//
 // Deprecated: Use github.com/bazelbuild/rules_go/go/runfiles instead to access
 // runfiles.
 const TEST_SRCDIR = "TEST_SRCDIR"
+
 const TEST_TMPDIR = "TEST_TMPDIR"
+
+// The name of the environment variable to access the test workspace name.
+//
 // Deprecated: Use github.com/bazelbuild/rules_go/go/runfiles instead to access
 // runfiles. With Bzlmod enabled, the corresponding environment variable has the
 // constant value "_main".
@@ -52,6 +58,7 @@ func TestTmpDir() string {
 // "-begin_files" and "-end_files" are used). Entries between these delimiters
 // are spliced out of from os.Args and returned to the caller.  If the ordering
 // of -begin_files or -end_files is malformed, error is returned.
+//
 // Deprecated: This method is meant for internal use by bazel_testing only.
 func SpliceDelimitedOSArgs(begin, end string) ([]string, error) {
 	var files []string

go/tools/bazel/runfiles.go

@@ -237,6 +237,7 @@ func ListRunfiles() ([]RunfileEntry, error) {
 // TestWorkspace returns the name of the Bazel workspace for this test.
 // TestWorkspace returns an error if the TEST_WORKSPACE environment variable
 // was not set or SetDefaultTestWorkspace was not called.
+//
 // Deprecated: With Bzlmod enabled, the workspace name is always "_main". Use
 // github.com/bazelbuild/rules_go/go/runfiles instead to access runfiles.
 func TestWorkspace() (string, error) {
@@ -252,6 +253,7 @@ func TestWorkspace() (string, error) {
 // SetDefaultTestWorkspace allows you to set a fake value for the
 // environment variable TEST_WORKSPACE if it is not defined. This is useful
 // when running tests on the command line and not through Bazel.
+//
 // Deprecated: With Bzlmod enabled, the workspace name is always "_main". Use
 // github.com/bazelbuild/rules_go/go/runfiles instead to access runfiles.
 func SetDefaultTestWorkspace(w string) {
@@ -263,6 +265,7 @@ func SetDefaultTestWorkspace(w string) {
 // It will return an error if there is no runfiles tree, for example because
 // the executable is run on Windows or was not invoked with 'bazel test'
 // or 'bazel run'.
+//
 // Deprecated: Use github.com/bazelbuild/rules_go/go/runfiles instead to access
 // runfiles, which provides a platform-agnostic fs.FS implementation.
 func RunfilesPath() (string, error) {