fix(gengapic): move top-level package doc links to top (#1175)

Fixes #1140
googleapis · Jan 9, 2023 · 8cf6194 · 8cf6194
1 parent 59fb73b
commit 8cf6194
Show file tree

Hide file tree

Showing 7 changed files with 35 additions and 21 deletions.
diff --git a/internal/gengapic/doc_file.go b/internal/gengapic/doc_file.go
@@ -65,6 +65,11 @@ func (g *generator) genDocFile(year int, scopes []string, serv *descriptor.Servi
 		p("//   NOTE: This package is in beta. It is not stable, and may be subject to changes.")
 	}
 
+	p("//")
+	p("// General documentation")
+	p("//")
+	p("// For information about setting deadlines, reusing contexts, and more")
+	p("// please visit https://pkg.go.dev/cloud.google.com/go.")
 	p("//")
 	p("// Example usage")
 	p("//")
@@ -103,9 +108,6 @@ func (g *generator) genDocFile(year int, scopes []string, serv *descriptor.Servi
 	p("// Individual methods on the client use the ctx given to them.")
 	p("//")
 	p("// To close the open connection, use the Close() method.")
-	p("//")
-	p("// For information about setting deadlines, reusing contexts, and more")
-	p("// please visit https://pkg.go.dev/cloud.google.com/go.")
 	p("package %s // import %q", g.opts.pkgName, g.opts.pkgPath)
 	p("")
 

diff --git a/internal/gengapic/testdata/doc_file.want b/internal/gengapic/testdata/doc_file.want
@@ -21,6 +21,11 @@
 // (at https://api.foo.com) with Buz (at https://api.buz.com) and Baz (at
 // https://api.baz.com) to acclerate bar.
 //
+// General documentation
+//
+// For information about setting deadlines, reusing contexts, and more
+// please visit https://pkg.go.dev/cloud.google.com/go.
+//
 // Example usage
 //
 // To get started with this package, create a client.
@@ -74,9 +79,6 @@
 // Individual methods on the client use the ctx given to them.
 //
 // To close the open connection, use the Close() method.
-//
-// For information about setting deadlines, reusing contexts, and more
-// please visit https://pkg.go.dev/cloud.google.com/go.
 package awesome // import "path/to/awesome"
 
 import (

diff --git a/internal/gengapic/testdata/doc_file_alpha.want b/internal/gengapic/testdata/doc_file_alpha.want
@@ -23,6 +23,11 @@
 //
 //   NOTE: This package is in alpha. It is not stable, and is likely to change.
 //
+// General documentation
+//
+// For information about setting deadlines, reusing contexts, and more
+// please visit https://pkg.go.dev/cloud.google.com/go.
+//
 // Example usage
 //
 // To get started with this package, create a client.
@@ -76,9 +81,6 @@
 // Individual methods on the client use the ctx given to them.
 //
 // To close the open connection, use the Close() method.
-//
-// For information about setting deadlines, reusing contexts, and more
-// please visit https://pkg.go.dev/cloud.google.com/go.
 package awesome // import "path/to/awesome"
 
 import (

diff --git a/internal/gengapic/testdata/doc_file_alpha_emptyservice.want b/internal/gengapic/testdata/doc_file_alpha_emptyservice.want
@@ -23,6 +23,11 @@
 //
 //   NOTE: This package is in alpha. It is not stable, and is likely to change.
 //
+// General documentation
+//
+// For information about setting deadlines, reusing contexts, and more
+// please visit https://pkg.go.dev/cloud.google.com/go.
+//
 // Example usage
 //
 // To get started with this package, create a client.
@@ -49,9 +54,6 @@
 // Individual methods on the client use the ctx given to them.
 //
 // To close the open connection, use the Close() method.
-//
-// For information about setting deadlines, reusing contexts, and more
-// please visit https://pkg.go.dev/cloud.google.com/go.
 package awesome // import "path/to/awesome"
 
 import (

diff --git a/internal/gengapic/testdata/doc_file_beta.want b/internal/gengapic/testdata/doc_file_beta.want
@@ -23,6 +23,11 @@
 //
 //   NOTE: This package is in beta. It is not stable, and may be subject to changes.
 //
+// General documentation
+//
+// For information about setting deadlines, reusing contexts, and more
+// please visit https://pkg.go.dev/cloud.google.com/go.
+//
 // Example usage
 //
 // To get started with this package, create a client.
@@ -76,9 +81,6 @@
 // Individual methods on the client use the ctx given to them.
 //
 // To close the open connection, use the Close() method.
-//
-// For information about setting deadlines, reusing contexts, and more
-// please visit https://pkg.go.dev/cloud.google.com/go.
 package awesome // import "path/to/awesome"
 
 import (

diff --git a/internal/gengapic/testdata/doc_file_beta_emptyservice.want b/internal/gengapic/testdata/doc_file_beta_emptyservice.want
@@ -23,6 +23,11 @@
 //
 //   NOTE: This package is in beta. It is not stable, and may be subject to changes.
 //
+// General documentation
+//
+// For information about setting deadlines, reusing contexts, and more
+// please visit https://pkg.go.dev/cloud.google.com/go.
+//
 // Example usage
 //
 // To get started with this package, create a client.
@@ -49,9 +54,6 @@
 // Individual methods on the client use the ctx given to them.
 //
 // To close the open connection, use the Close() method.
-//
-// For information about setting deadlines, reusing contexts, and more
-// please visit https://pkg.go.dev/cloud.google.com/go.
 package awesome // import "path/to/awesome"
 
 import (

diff --git a/internal/gengapic/testdata/doc_file_emptyservice.want b/internal/gengapic/testdata/doc_file_emptyservice.want
@@ -21,6 +21,11 @@
 // (at https://api.foo.com) with Buz (at https://api.buz.com) and Baz (at
 // https://api.baz.com) to acclerate bar.
 //
+// General documentation
+//
+// For information about setting deadlines, reusing contexts, and more
+// please visit https://pkg.go.dev/cloud.google.com/go.
+//
 // Example usage
 //
 // To get started with this package, create a client.
@@ -47,9 +52,6 @@
 // Individual methods on the client use the ctx given to them.
 //
 // To close the open connection, use the Close() method.
-//
-// For information about setting deadlines, reusing contexts, and more
-// please visit https://pkg.go.dev/cloud.google.com/go.
 package awesome // import "path/to/awesome"
 
 import (