Improve examples

device/examples_test.go

@@ -1,29 +1,31 @@
-package device
+package device_test
 
 import (
 	"context"
 	"fmt"
 	"net/http"
 	"os"
+
+	"github.com/cli/oauth/device"
 )
 
 // This demonstrates how to perform OAuth Device Authorization Flow for GitHub.com.
 // After RequestCode successfully completes, the client app should prompt the user to copy
 // the UserCode and to open VerificationURI in their web browser to enter the code.
-func Example() {
+func ExampleRequestCode() {
 	clientID := os.Getenv("OAUTH_CLIENT_ID")
 	scopes := []string{"repo", "read:org"}
 	httpClient := http.DefaultClient
 
-	code, err := RequestCode(httpClient, "https://github.com/login/device/code", clientID, scopes)
+	code, err := device.RequestCode(httpClient, "https://github.com/login/device/code", clientID, scopes)
 	if err != nil {
 		panic(err)
 	}
 
 	fmt.Printf("Copy code: %s\n", code.UserCode)
 	fmt.Printf("then open: %s\n", code.VerificationURI)
 
-	accessToken, err := Wait(context.TODO(), httpClient, "https://github.com/login/oauth/access_token", WaitOptions{
+	accessToken, err := device.Wait(context.TODO(), httpClient, "https://github.com/login/oauth/access_token", device.WaitOptions{
 		ClientID:   clientID,
 		DeviceCode: code,
 	})

examples_test.go

@@ -1,16 +1,19 @@
-package oauth
+package oauth_test
 
 import (
 	"fmt"
 	"os"
+
+	"github.com/cli/oauth"
 )
 
-// Try initiating OAuth Device flow on the server and fall back to OAuth Web application flow if
-// Device flow seems unsupported. This approach isn't strictly needed for github.com, as its Device
-// flow support is globally available, but enables logging in to hosted GitHub instances as well.
-func Example() {
-	flow := &Flow{
-		Host:         GitHubHost("https://github.com"),
+// DetectFlow attempts to initiate OAuth Device flow with the server and falls back to OAuth Web
+// application flow if Device flow seems unsupported. This approach isn't strictly needed for
+// github.com, as its Device flow support is globally available, but it enables logging in to
+// self-hosted GitHub instances as well.
+func ExampleFlow_DetectFlow() {
+	flow := &oauth.Flow{
+		Host:         oauth.GitHubHost("https://github.com"),
 		ClientID:     os.Getenv("OAUTH_CLIENT_ID"),
 		ClientSecret: os.Getenv("OAUTH_CLIENT_SECRET"), // only applicable to web app flow
 		CallbackURI:  "http://127.0.0.1/callback",      // only applicable to web app flow

webapp/examples_test.go

@@ -1,4 +1,4 @@
-package webapp
+package webapp_test
 
 import (
 	"context"
@@ -7,22 +7,23 @@ import (
 	"os"
 
 	"github.com/cli/browser"
+	"github.com/cli/oauth/webapp"
 )
 
-// This demonstrates how to perform OAuth App Authorization Flow for GitHub.com.
-// Ensure that the OAuth app on GitHub lists the callback URL: "http://127.0.0.1/callback"
-func Example() {
+// Initiate the OAuth App Authorization Flow for GitHub.com.
+func ExampleInitFlow() {
 	clientID := os.Getenv("OAUTH_CLIENT_ID")
 	clientSecret := os.Getenv("OAUTH_CLIENT_SECRET")
+	callbackURL := "http://127.0.0.1/callback"
 
-	flow, err := InitFlow()
+	flow, err := webapp.InitFlow()
 	if err != nil {
 		panic(err)
 	}
 
-	params := BrowserParams{
+	params := webapp.BrowserParams{
 		ClientID:    clientID,
-		RedirectURI: "http://127.0.0.1/callback",
+		RedirectURI: callbackURL,
 		Scopes:      []string{"repo", "read:org"},
 		AllowSignup: true,
 	}
@@ -43,7 +44,7 @@ func Example() {
 	}
 
 	httpClient := http.DefaultClient
-	accessToken, err := flow.Wait(context.TODO(), httpClient, "https://github.com/login/oauth/access_token", WaitOptions{
+	accessToken, err := flow.Wait(context.TODO(), httpClient, "https://github.com/login/oauth/access_token", webapp.WaitOptions{
 		ClientSecret: clientSecret,
 	})
 	if err != nil {