Add documentation comments.

device.go

@@ -24,17 +24,21 @@ type RootDevice struct {
 	Device      Device      `xml:"device"`
 }
 
+// SetURLBase sets the URLBase for the RootDevice and its underlying components.
 func (root *RootDevice) SetURLBase(urlBase *url.URL) {
 	root.URLBase = *urlBase
 	root.URLBaseStr = urlBase.String()
 	root.Device.SetURLBase(urlBase)
 }
 
+// SpecVersion is part of a RootDevice, describes the version of the
+// specification that the data adheres to.
 type SpecVersion struct {
 	Major int32 `xml:"major"`
 	Minor int32 `xml:"minor"`
 }
 
+// Device is a UPnP device. It can have child devices.
 type Device struct {
 	DeviceType       string    `xml:"deviceType"`
 	FriendlyName     string    `xml:"friendlyName"`
@@ -55,6 +59,7 @@ type Device struct {
 	PresentationURL URLField `xml:"presentationURL"`
 }
 
+// VisitDevices calls visitor for the device, and all its descendent devices.
 func (device *Device) VisitDevices(visitor func(*Device)) {
 	visitor(device)
 	for i := range device.Devices {
@@ -62,6 +67,8 @@ func (device *Device) VisitDevices(visitor func(*Device)) {
 	}
 }
 
+// VisitServices calls visitor for all Services under the device and all its
+// descendent devices.
 func (device *Device) VisitServices(visitor func(*Service)) {
 	device.VisitDevices(func(d *Device) {
 		for i := range device.Services {
@@ -70,6 +77,8 @@ func (device *Device) VisitServices(visitor func(*Service)) {
 	})
 }
 
+// FindService finds all (if any) Services under the device and its descendents
+// that have the given ServiceType.
 func (device *Device) FindService(serviceType string) []*Service {
 	var services []*Service
 	device.VisitServices(func(s *Service) {
@@ -81,6 +90,7 @@ func (device *Device) FindService(serviceType string) []*Service {
 	return services
 }
 
+// SetURLBase sets the URLBase for the Device and its underlying components.
 func (device *Device) SetURLBase(urlBase *url.URL) {
 	device.ManufacturerURL.SetURLBase(urlBase)
 	device.ModelURL.SetURLBase(urlBase)
@@ -100,6 +110,8 @@ func (device *Device) String() string {
 	return fmt.Sprintf("Device ID %s : %s (%s)", device.UDN, device.DeviceType, device.FriendlyName)
 }
 
+// Icon is a representative image that a device might include in its
+// description.
 type Icon struct {
 	Mimetype string   `xml:"mimetype"`
 	Width    int32    `xml:"width"`
@@ -108,10 +120,12 @@ type Icon struct {
 	URL      URLField `xml:"url"`
 }
 
+// SetURLBase sets the URLBase for the Icon.
 func (icon *Icon) SetURLBase(url *url.URL) {
 	icon.URL.SetURLBase(url)
 }
 
+// Service is a service provided by a UPnP Device.
 type Service struct {
 	ServiceType string   `xml:"serviceType"`
 	ServiceId   string   `xml:"serviceId"`
@@ -120,6 +134,7 @@ type Service struct {
 	EventSubURL URLField `xml:"eventSubURL"`
 }
 
+// SetURLBase sets the URLBase for the Service.
 func (srv *Service) SetURLBase(urlBase *url.URL) {
 	srv.SCPDURL.SetURLBase(urlBase)
 	srv.ControlURL.SetURLBase(urlBase)
@@ -130,6 +145,8 @@ func (srv *Service) String() string {
 	return fmt.Sprintf("Service ID %s : %s", srv.ServiceId, srv.ServiceType)
 }
 
+// RequestSCDP requests the SCPD (soap actions and state variables description)
+// for the service.
 func (srv *Service) RequestSCDP() (*SCPD, error) {
 	if !srv.SCPDURL.Ok {
 		return nil, errors.New("bad/missing SCPD URL, or no URLBase has been set")
@@ -141,6 +158,7 @@ func (srv *Service) RequestSCDP() (*SCPD, error) {
 	return scpd, nil
 }
 
+// URLField is a URL that is part of a device description.
 type URLField struct {
 	URL url.URL `xml:"-"`
 	Ok  bool    `xml:"-"`

goupnp.go

@@ -25,6 +25,7 @@ const (
 	DeviceTypeInternetGatewayDevice = "urn:schemas-upnp-org:device:InternetGatewayDevice:1"
 )
 
+// ContextError is an error that wraps an error with some context information.
 type ContextError struct {
 	Context string
 	Err     error
@@ -34,6 +35,7 @@ func (err ContextError) Error() string {
 	return fmt.Sprintf("%s: %v", err.Context, err.Err)
 }
 
+// MaybeRootDevice contains either a RootDevice or an error.
 type MaybeRootDevice struct {
 	Root *RootDevice
 	Err  error