cmd/tailscale/cli/jsonoutput: provide examples for jsonoutput.DNS* (#19998)

This patch adds examples for unmarshalling the JSON outputs of the
following commands:

	tailscale dns query --json
	tailscale dns status --json

It also adds an example usage of `tailscale dns` to both
jsonoutput.DNSQueryResult and jsonoutput.DNSStatusResult.

Updates #13326
Updates #18750

Signed-off-by: Simon Law <sfllaw@tailscale.com>

cmd/tailscale/cli/jsonoutput/dns.go

@@ -51,7 +51,9 @@ type DNSTailnetInfo struct {
 }
 
 // DNSStatusResult is the full DNS status collected from the local
-// Tailscale daemon.
+// Tailscale daemon. It is the output of:
+//
+//	$ tailscale dns status --json
 type DNSStatusResult struct {
 	// TailscaleDNS is whether the Tailscale DNS configuration is
 	// installed on this device (the --accept-dns setting).
@@ -107,7 +109,9 @@ type DNSAnswer struct {
 }
 
 // DNSQueryResult is the result of a DNS query via the Tailscale
-// internal forwarder (100.100.100.100).
+// internal forwarder (100.100.100.100). It is the output of:
+//
+//	$ tailscale dns query --json NAME
 type DNSQueryResult struct {
 	Name         string
 	QueryType    string            // e.g. "A", "AAAA"

cmd/tailscale/cli/jsonoutput/example_dnsqueryresult_test.go

@@ -0,0 +1,31 @@
+// Copyright (c) Tailscale Inc & contributors
+// SPDX-License-Identifier: BSD-3-Clause
+
+package jsonoutput_test
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+
+	"tailscale.com/cmd/tailscale/cli/jsonoutput"
+)
+
+func ExampleDNSQueryResult() {
+	cmd := exec.Command("tailscale", "dns", "query", "--json", "hello.ts.net")
+	out, err := cmd.Output()
+	if err != nil {
+		if err, ok := errors.AsType[*exec.ExitError](err); ok {
+			fmt.Fprintf(os.Stderr, "%s", err.Stderr)
+		}
+		panic(err)
+	}
+
+	var dnsQuery jsonoutput.DNSQueryResult
+	if err := json.Unmarshal(out, &dnsQuery); err != nil {
+		panic(err)
+	}
+	fmt.Printf("{type: %s, name: %q}\n", dnsQuery.QueryType, dnsQuery.Name)
+}

cmd/tailscale/cli/jsonoutput/example_dnsstatusresult_test.go

@@ -0,0 +1,31 @@
+// Copyright (c) Tailscale Inc & contributors
+// SPDX-License-Identifier: BSD-3-Clause
+
+package jsonoutput_test
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"os/exec"
+
+	"tailscale.com/cmd/tailscale/cli/jsonoutput"
+)
+
+func ExampleDNSStatusResult() {
+	cmd := exec.Command("tailscale", "dns", "status", "--json")
+	out, err := cmd.Output()
+	if err != nil {
+		if err, ok := errors.AsType[*exec.ExitError](err); ok {
+			fmt.Fprintf(os.Stderr, "%s", err.Stderr)
+		}
+		panic(err)
+	}
+
+	var dnsStatus jsonoutput.DNSStatusResult
+	if err := json.Unmarshal(out, &dnsStatus); err != nil {
+		panic(err)
+	}
+	fmt.Printf("{accept-dns: %t, resolvers: %q}\n", dnsStatus.TailscaleDNS, dnsStatus.Resolvers)
+}