Repository: googleapis/gapic-generator-go
Pull request #1375 (2023-07-17 19:08:59)

fix: update client docs to ref base docs more
Some users have not been able to find some of our base package docs. Let's explicitly link to some more of these docs so it is easy to search for.

Related internal bugs: 288887575, 288883068, 288883059
Related PR: https://github.com/googleapis/google-cloud-go/pull/8274


Patch:
diff --git a/internal/gengapic/doc_file.go b/internal/gengapic/doc_file.go
index 6adb868..1066866 100644
--- a/internal/gengapic/doc_file.go
+++ b/internal/gengapic/doc_file.go
@@ -67,8 +67,15 @@ func (g *generator) genDocFile(year int, scopes []string, serv *descriptor.Servi
 	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("// For information that is relevant for all client libraries please reference")
+	p("// https://pkg.go.dev/cloud.google.com/go#pkg-overview. Some information on this")
+	p("// page includes:")
+	p("//")
+	p("//  - [Authentication and Authorization]")
+	p("//  - [Timeouts and Cancellation]")
+	p("//  - [Testing against Client Libraries]")
+	p("//  - [Debugging Client Libraries]")
+	p("//  - [Inspecting errors]")
 	p("//")
 	p("// Example usage")
 	p("//")
@@ -100,12 +107,6 @@ func (g *generator) genDocFile(year int, scopes []string, serv *descriptor.Servi
 		g.codesnippet(snipMethod)
 	}
 
-	p("// Inspecting errors")
-	p("//")
-	p("// To see examples of how to inspect errors returned by this package please reference")
-	p("// [Inspecting errors](https://pkg.go.dev/cloud.google.com/go#hdr-Inspecting_errors).")
-	p("//")
-
 	p("// Use of Context")
 	p("//")
 	p("// The ctx passed to New%sClient is used for authentication requests and", servName)
@@ -113,6 +114,12 @@ 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("// [Authentication and Authorization]: https://pkg.go.dev/cloud.google.com/go#hdr-Authentication_and_Authorization")
+	p("// [Timeouts and Cancellation]: https://pkg.go.dev/cloud.google.com/go#hdr-Timeouts_and_Cancellation")
+	p("// [Testing against Client Libraries]: https://pkg.go.dev/cloud.google.com/go#hdr-Testing")
+	p("// [Debugging Client Libraries]: https://pkg.go.dev/cloud.google.com/go#hdr-Debugging")
+	p("// [Inspecting errors]: https://pkg.go.dev/cloud.google.com/go#hdr-Inspecting_errors")
 	p("package %s // import %q", g.opts.pkgName, g.opts.pkgPath)
 	p("")
 


Test patch:
diff --git a/internal/gengapic/testdata/doc_file.want b/internal/gengapic/testdata/doc_file.want
index 23d3612..cbae1e4 100644
--- a/internal/gengapic/testdata/doc_file.want
+++ b/internal/gengapic/testdata/doc_file.want
@@ -23,8 +23,15 @@
 //
 // General documentation
 //
-// For information about setting deadlines, reusing contexts, and more
-// please visit https://pkg.go.dev/cloud.google.com/go.
+// For information that is relevant for all client libraries please reference
+// https://pkg.go.dev/cloud.google.com/go#pkg-overview. Some information on this
+// page includes:
+//
+//  - [Authentication and Authorization]
+//  - [Timeouts and Cancellation]
+//  - [Testing against Client Libraries]
+//  - [Debugging Client Libraries]
+//  - [Inspecting errors]
 //
 // Example usage
 //
@@ -72,11 +79,6 @@
 //  // TODO: Use resp.
 //  _ = resp
 //
-// Inspecting errors
-//
-// To see examples of how to inspect errors returned by this package please reference
-// [Inspecting errors](https://pkg.go.dev/cloud.google.com/go#hdr-Inspecting_errors).
-//
 // Use of Context
 //
 // The ctx passed to NewFooClient is used for authentication requests and
@@ -84,6 +86,12 @@
 // Individual methods on the client use the ctx given to them.
 //
 // To close the open connection, use the Close() method.
+//
+// [Authentication and Authorization]: https://pkg.go.dev/cloud.google.com/go#hdr-Authentication_and_Authorization
+// [Timeouts and Cancellation]: https://pkg.go.dev/cloud.google.com/go#hdr-Timeouts_and_Cancellation
+// [Testing against Client Libraries]: https://pkg.go.dev/cloud.google.com/go#hdr-Testing
+// [Debugging Client Libraries]: https://pkg.go.dev/cloud.google.com/go#hdr-Debugging
+// [Inspecting errors]: https://pkg.go.dev/cloud.google.com/go#hdr-Inspecting_errors
 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
index 7f332d2..cb422e5 100644
--- a/internal/gengapic/testdata/doc_file_alpha.want
+++ b/internal/gengapic/testdata/doc_file_alpha.want
@@ -25,8 +25,15 @@
 //
 // General documentation
 //
-// For information about setting deadlines, reusing contexts, and more
-// please visit https://pkg.go.dev/cloud.google.com/go.
+// For information that is relevant for all client libraries please reference
+// https://pkg.go.dev/cloud.google.com/go#pkg-overview. Some information on this
+// page includes:
+//
+//  - [Authentication and Authorization]
+//  - [Timeouts and Cancellation]
+//  - [Testing against Client Libraries]
+//  - [Debugging Client Libraries]
+//  - [Inspecting errors]
 //
 // Example usage
 //
@@ -74,11 +81,6 @@
 //  // TODO: Use resp.
 //  _ = resp
 //
-// Inspecting errors
-//
-// To see examples of how to inspect errors returned by this package please reference
-// [Inspecting errors](https://pkg.go.dev/cloud.google.com/go#hdr-Inspecting_errors).
-//
 // Use of Context
 //
 // The ctx passed to NewFooClient is used for authentication requests and
@@ -86,6 +88,12 @@
 // Individual methods on the client use the ctx given to them.
 //
 // To close the open connection, use the Close() method.
+//
+// [Authentication and Authorization]: https://pkg.go.dev/cloud.google.com/go#hdr-Authentication_and_Authorization
+// [Timeouts and Cancellation]: https://pkg.go.dev/cloud.google.com/go#hdr-Timeouts_and_Cancellation
+// [Testing against Client Libraries]: https://pkg.go.dev/cloud.google.com/go#hdr-Testing
+// [Debugging Client Libraries]: https://pkg.go.dev/cloud.google.com/go#hdr-Debugging
+// [Inspecting errors]: https://pkg.go.dev/cloud.google.com/go#hdr-Inspecting_errors
 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
index 5221f7f..4ca85b0 100644
--- a/internal/gengapic/testdata/doc_file_alpha_emptyservice.want
+++ b/internal/gengapic/testdata/doc_file_alpha_emptyservice.want
@@ -25,8 +25,15 @@
 //
 // General documentation
 //
-// For information about setting deadlines, reusing contexts, and more
-// please visit https://pkg.go.dev/cloud.google.com/go.
+// For information that is relevant for all client libraries please reference
+// https://pkg.go.dev/cloud.google.com/go#pkg-overview. Some information on this
+// page includes:
+//
+//  - [Authentication and Authorization]
+//  - [Timeouts and Cancellation]
+//  - [Testing against Client Libraries]
+//  - [Debugging Client Libraries]
+//  - [Inspecting errors]
 //
 // Example usage
 //
@@ -47,11 +54,6 @@
 // The methods of Client are safe for concurrent use by multiple goroutines.
 // The returned client must be Closed when it is done being used.
 //
-// Inspecting errors
-//
-// To see examples of how to inspect errors returned by this package please reference
-// [Inspecting errors](https://pkg.go.dev/cloud.google.com/go#hdr-Inspecting_errors).
-//
 // Use of Context
 //
 // The ctx passed to NewFooClient is used for authentication requests and
@@ -59,6 +61,12 @@
 // Individual methods on the client use the ctx given to them.
 //
 // To close the open connection, use the Close() method.
+//
+// [Authentication and Authorization]: https://pkg.go.dev/cloud.google.com/go#hdr-Authentication_and_Authorization
+// [Timeouts and Cancellation]: https://pkg.go.dev/cloud.google.com/go#hdr-Timeouts_and_Cancellation
+// [Testing against Client Libraries]: https://pkg.go.dev/cloud.google.com/go#hdr-Testing
+// [Debugging Client Libraries]: https://pkg.go.dev/cloud.google.com/go#hdr-Debugging
+// [Inspecting errors]: https://pkg.go.dev/cloud.google.com/go#hdr-Inspecting_errors
 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
index f301d2a..c0ed58f 100644
--- a/internal/gengapic/testdata/doc_file_beta.want
+++ b/internal/gengapic/testdata/doc_file_beta.want
@@ -25,8 +25,15 @@
 //
 // General documentation
 //
-// For information about setting deadlines, reusing contexts, and more
-// please visit https://pkg.go.dev/cloud.google.com/go.
+// For information that is relevant for all client libraries please reference
+// https://pkg.go.dev/cloud.google.com/go#pkg-overview. Some information on this
+// page includes:
+//
+//  - [Authentication and Authorization]
+//  - [Timeouts and Cancellation]
+//  - [Testing against Client Libraries]
+//  - [Debugging Client Libraries]
+//  - [Inspecting errors]
 //
 // Example usage
 //
@@ -74,11 +81,6 @@
 //  // TODO: Use resp.
 //  _ = resp
 //
-// Inspecting errors
-//
-// To see examples of how to inspect errors returned by this package please reference
-// [Inspecting errors](https://pkg.go.dev/cloud.google.com/go#hdr-Inspecting_errors).
-//
 // Use of Context
 //
 // The ctx passed to NewFooClient is used for authentication requests and
@@ -86,6 +88,12 @@
 // Individual methods on the client use the ctx given to them.
 //
 // To close the open connection, use the Close() method.
+//
+// [Authentication and Authorization]: https://pkg.go.dev/cloud.google.com/go#hdr-Authentication_and_Authorization
+// [Timeouts and Cancellation]: https://pkg.go.dev/cloud.google.com/go#hdr-Timeouts_and_Cancellation
+// [Testing against Client Libraries]: https://pkg.go.dev/cloud.google.com/go#hdr-Testing
+// [Debugging Client Libraries]: https://pkg.go.dev/cloud.google.com/go#hdr-Debugging
+// [Inspecting errors]: https://pkg.go.dev/cloud.google.com/go#hdr-Inspecting_errors
 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
index 593fa1e..ec9b819 100644
--- a/internal/gengapic/testdata/doc_file_beta_emptyservice.want
+++ b/internal/gengapic/testdata/doc_file_beta_emptyservice.want
@@ -25,8 +25,15 @@
 //
 // General documentation
 //
-// For information about setting deadlines, reusing contexts, and more
-// please visit https://pkg.go.dev/cloud.google.com/go.
+// For information that is relevant for all client libraries please reference
+// https://pkg.go.dev/cloud.google.com/go#pkg-overview. Some information on this
+// page includes:
+//
+//  - [Authentication and Authorization]
+//  - [Timeouts and Cancellation]
+//  - [Testing against Client Libraries]
+//  - [Debugging Client Libraries]
+//  - [Inspecting errors]
 //
 // Example usage
 //
@@ -47,11 +54,6 @@
 // The methods of Client are safe for concurrent use by multiple goroutines.
 // The returned client must be Closed when it is done being used.
 //
-// Inspecting errors
-//
-// To see examples of how to inspect errors returned by this package please reference
-// [Inspecting errors](https://pkg.go.dev/cloud.google.com/go#hdr-Inspecting_errors).
-//
 // Use of Context
 //
 // The ctx passed to NewFooClient is used for authentication requests and
@@ -59,6 +61,12 @@
 // Individual methods on the client use the ctx given to them.
 //
 // To close the open connection, use the Close() method.
+//
+// [Authentication and Authorization]: https://pkg.go.dev/cloud.google.com/go#hdr-Authentication_and_Authorization
+// [Timeouts and Cancellation]: https://pkg.go.dev/cloud.google.com/go#hdr-Timeouts_and_Cancellation
+// [Testing against Client Libraries]: https://pkg.go.dev/cloud.google.com/go#hdr-Testing
+// [Debugging Client Libraries]: https://pkg.go.dev/cloud.google.com/go#hdr-Debugging
+// [Inspecting errors]: https://pkg.go.dev/cloud.google.com/go#hdr-Inspecting_errors
 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
index c24d076..e2f2880 100644
--- a/internal/gengapic/testdata/doc_file_emptyservice.want
+++ b/internal/gengapic/testdata/doc_file_emptyservice.want
@@ -23,8 +23,15 @@
 //
 // General documentation
 //
-// For information about setting deadlines, reusing contexts, and more
-// please visit https://pkg.go.dev/cloud.google.com/go.
+// For information that is relevant for all client libraries please reference
+// https://pkg.go.dev/cloud.google.com/go#pkg-overview. Some information on this
+// page includes:
+//
+//  - [Authentication and Authorization]
+//  - [Timeouts and Cancellation]
+//  - [Testing against Client Libraries]
+//  - [Debugging Client Libraries]
+//  - [Inspecting errors]
 //
 // Example usage
 //
@@ -45,11 +52,6 @@
 // The methods of Client are safe for concurrent use by multiple goroutines.
 // The returned client must be Closed when it is done being used.
 //
-// Inspecting errors
-//
-// To see examples of how to inspect errors returned by this package please reference
-// [Inspecting errors](https://pkg.go.dev/cloud.google.com/go#hdr-Inspecting_errors).
-//
 // Use of Context
 //
 // The ctx passed to NewFooClient is used for authentication requests and
@@ -57,6 +59,12 @@
 // Individual methods on the client use the ctx given to them.
 //
 // To close the open connection, use the Close() method.
+//
+// [Authentication and Authorization]: https://pkg.go.dev/cloud.google.com/go#hdr-Authentication_and_Authorization
+// [Timeouts and Cancellation]: https://pkg.go.dev/cloud.google.com/go#hdr-Timeouts_and_Cancellation
+// [Testing against Client Libraries]: https://pkg.go.dev/cloud.google.com/go#hdr-Testing
+// [Debugging Client Libraries]: https://pkg.go.dev/cloud.google.com/go#hdr-Debugging
+// [Inspecting errors]: https://pkg.go.dev/cloud.google.com/go#hdr-Inspecting_errors
 package awesome // import "path/to/awesome"
 
 import (