Add example code, and improve the facing docs slightly.

cmd/discoverigd/discoverigd.go

@@ -1,36 +0,0 @@
-// Serves as a simple example/test of discovering UPnP devices on the local
-// network.
-package main
-
-import (
-	"fmt"
-
-	"github.com/huin/goupnp/dcps/internetgateway1"
-)
-
-func main() {
-	clients, errors, err := internetgateway1.NewWANPPPConnection1Clients()
-	if err != nil {
-		fmt.Println("Error discovering service with UPnP: ", err)
-		return
-	}
-
-	if len(errors) > 0 {
-		fmt.Printf("Error discovering %d services:\n", len(errors))
-		for _, err := range errors {
-			fmt.Println("  ", err)
-		}
-	}
-
-	fmt.Printf("Successfully discovered %d services:\n", len(clients))
-	for _, client := range clients {
-		device := &client.RootDevice.Device
-
-		fmt.Println("  Device:", device.FriendlyName)
-		if addr, err := client.GetExternalIPAddress(); err != nil {
-			fmt.Printf("    Failed to get external IP address: %v\n", err)
-		} else {
-			fmt.Printf("    External IP address: %v\n", addr)
-		}
-	}
-}

example/example.go

@@ -0,0 +1,6 @@
+// Serves as examples of using the goupnp library.
+//
+// To run examples and see the output for your local network, run the following
+// command (specifically including the -v flag):
+//     go test -v github.com/huin/goupnp/example
+package example

example/example_test.go

@@ -0,0 +1,48 @@
+package example_test
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/huin/goupnp/dcps/internetgateway1"
+)
+
+// Discovering a internet gateway devices on the local network, and asking each
+// of them for their external IP address.
+func Example_getExternalIPAddress() {
+	// import (
+	//   "fmt"
+	//   "os"
+	//   "github.com/huin/goupnp/dcps/internetgateway1"
+	// )
+	fmt.Println("Running")
+	clients, errors, err := internetgateway1.NewWANPPPConnection1Clients()
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "Error discovering service with UPnP: ", err)
+		return
+	}
+
+	if len(errors) > 0 {
+		fmt.Fprintf(os.Stderr, "Error discovering %d services:\n", len(errors))
+		for _, err := range errors {
+			fmt.Println("  ", err)
+		}
+	}
+
+	fmt.Fprintf(os.Stderr, "Successfully discovered %d services:\n", len(clients))
+	for _, client := range clients {
+		device := &client.RootDevice.Device
+
+		fmt.Fprintln(os.Stderr, "  Device:", device.FriendlyName)
+		if addr, err := client.GetExternalIPAddress(); err != nil {
+			fmt.Fprintf(os.Stderr, "    Failed to get external IP address: %v\n", err)
+		} else {
+			fmt.Fprintf(os.Stderr, "    External IP address: %v\n", addr)
+		}
+	}
+	fmt.Println("Complete")
+
+	// Output:
+	// Running
+	// Complete
+}

goupnp.go

@@ -1,4 +1,17 @@
-// goupnp is an implementation of a client for UPnP devices.
+// goupnp is an implementation of a client for various UPnP services.
+//
+// For most uses, it is recommended to use the code-generated packages under
+// github.com/huin/goupnp/dcps. Example use is shown at
+// http://godoc.org/github.com/huin/goupnp/example
+//
+// A commonly used client is internetgateway1.WANPPPConnection1:
+// http://godoc.org/github.com/huin/goupnp/dcps/internetgateway1#WANPPPConnection1
+//
+// Currently only a couple of schemas have code generated for them from the
+// UPnP example XML specifications. Not all methods will work on these clients,
+// because the generated stubs contain the full set of specified methods from
+// the XML specifications, and the discovered services will likely support a
+// subset of those methods.
 package goupnp
 
 import (