docs: add WithApplication and action waiting to code example (#808)

The code example in our README.md only contained a minimal example
showing how to set up the client and make a simple GET request.

This introduces two additional "features" to the example:

1. We sometimes get support requests from users who forget to wait for
the returned actions and expect the server (or other resource) to be
immediately ready.

2. We regularly get support requests from users where the rate limit is
exhausted by tools that do not identify themselves. This makes it hard
to help users, as we are missing information.

By showing the best-practices for both of these cases in the example, I
hope that more people adopt them and have a better experience overall.

Additionally I added the example to the go package docs for `hcloud`, so
it also shows up on pkgs.go.dev for the package.

Author: apricote

README.md

@@ -28,25 +28,47 @@ go get github.com/hetznercloud/hcloud-go/v2/hcloud
 package main
 
 import (
-    "context"
-    "fmt"
-    "log"
+	"context"
+	"fmt"
+	"log"
 
-    "github.com/hetznercloud/hcloud-go/v2/hcloud"
+	"github.com/hetznercloud/hcloud-go/v2/hcloud"
+	"github.com/hetznercloud/hcloud-go/v2/hcloud/exp/actionutil"
 )
 
 func main() {
-    client := hcloud.NewClient(hcloud.WithToken("token"))
-
-    server, _, err := client.Server.GetByID(context.Background(), 1)
-    if err != nil {
-        log.Fatalf("error retrieving server: %s\n", err)
-    }
-    if server != nil {
-        fmt.Printf("server 1 is called %q\n", server.Name)
-    } else {
-        fmt.Println("server 1 not found")
-    }
+	ctx := context.Background()
+
+	client := hcloud.NewClient(
+		hcloud.WithToken("token"),
+		hcloud.WithApplication("my-tool", "v1.0.0"),
+	)
+
+	result, _, err := client.Server.Create(ctx, hcloud.ServerCreateOpts{
+		Name:       "Foo",
+		Image:      &hcloud.Image{Name: "ubuntu-24.0"},
+		ServerType: &hcloud.ServerType{Name: "cpx22"},
+		Location:   &hcloud.Location{Name: "hel1"},
+	})
+	if err != nil {
+		log.Fatalf("error creating server: %s\n", err)
+	}
+
+	// Always await any returned actions, to make sure the async process is completed before you use the result:
+	err = client.Action.WaitFor(ctx, actionutil.AppendNext(result.Action, result.NextActions)...)
+	if err != nil {
+		log.Fatalf("error creating server: %s\n", err)
+	}
+
+	server, _, err := client.Server.GetByID(ctx, result.Server.ID)
+	if err != nil {
+		log.Fatalf("error retrieving server: %s\n", err)
+	}
+	if server != nil {
+		fmt.Printf("server is called %q\n", server.Name) // prints 'server is called "Foo"'
+	} else {
+		fmt.Println("server not found")
+	}
 }
 ```
 

hcloud/hcloud.go

@@ -7,6 +7,54 @@ Make sure to follow our API changelog available at https://docs.hetzner.cloud/ch
 (or the RRS feed available at https://docs.hetzner.cloud/changelog/feed.rss) to be
 notified about additions, deprecations and removals.
 
+# Example
+
+	package main
+
+	import (
+		"context"
+		"fmt"
+		"log"
+
+		"github.com/hetznercloud/hcloud-go/v2/hcloud"
+		"github.com/hetznercloud/hcloud-go/v2/hcloud/exp/actionutil"
+	)
+
+	func main() {
+		ctx := context.Background()
+
+		client := hcloud.NewClient(
+			hcloud.WithToken("token"),
+			hcloud.WithApplication("my-tool", "v1.0.0"),
+		)
+
+		result, _, err := client.Server.Create(ctx, hcloud.ServerCreateOpts{
+			Name:       "Foo",
+			Image:      &hcloud.Image{Name: "ubuntu-24.0"},
+			ServerType: &hcloud.ServerType{Name: "cpx22"},
+			Location:   &hcloud.Location{Name: "hel1"},
+		})
+		if err != nil {
+			log.Fatalf("error creating server: %s\n", err)
+		}
+
+		// Always await any returned actions, to make sure the async process is completed before you use the result:
+		err = client.Action.WaitFor(ctx, actionutil.AppendNext(result.Action, result.NextActions)...)
+		if err != nil {
+			log.Fatalf("error creating server: %s\n", err)
+		}
+
+		server, _, err := client.Server.GetByID(ctx, result.Server.ID)
+		if err != nil {
+			log.Fatalf("error retrieving server: %s\n", err)
+		}
+		if server != nil {
+			fmt.Printf("server is called %q\n", server.Name) // prints 'server is called "Foo"'
+		} else {
+			fmt.Println("server not found")
+		}
+	}
+
 # Retry mechanism
 
 The [Client.Do] method will retry failed requests that match certain criteria. The