Generate documentation comments from service template.

v2alpha/cmd/goupnp2srvgen/main.go

@@ -184,11 +184,21 @@ type tmplArgs struct {
 
 type imports struct {
 	// Maps from a type name like "ui4" to the `alias.name` for the import.
-	TypeRefByTypeName map[string]string
+	TypeByName map[string]typeDesc
 	// Each required import line, ordered by path.
 	ImportLines []importItem
 }
 
+type typeDesc struct {
+	// How to refer to the type, e.g. `pkg.Name`.
+	Ref string
+	// How to refer to the type absolutely (but not valid Go), e.g.
+	// `"github.com/foo/bar/pkg".Name`.
+	AbsRef string
+	// Name of the type without package, e.g. `Name`.
+	Name string
+}
+
 type importItem struct {
 	Alias string
 	Path  string
@@ -240,24 +250,29 @@ func accumulateImports(srvDesc *srvdesc.SCPD, typeMap typedesc.TypeMap) (*import
 		aliasByPath[path] = alias
 	}
 
-	// Populate typeRefByTypeName.
-	typeRefByTypeName := make(map[string]string, len(typeNames))
+	// Populate typeByName.
+	typeByName := make(map[string]typeDesc, len(typeNames))
 	for typeName := range typeNames {
 		goType := typeMap[typeName]
 		pkgPath := goType.GoType.PkgPath()
 		alias := aliasByPath[pkgPath]
+		td := typeDesc{
+			Name: goType.GoType.Name(),
+		}
 		if alias == "" {
 			// Builtin type.
-			typeRefByTypeName[typeName] = goType.GoType.Name()
+			td.AbsRef = td.Name
+			td.Ref = td.Name
 		} else {
-			typeRefByTypeName[typeName] = fmt.Sprintf(
-				"%s.%s", alias, goType.GoType.Name())
+			td.AbsRef = strconv.Quote(pkgPath) + "." + td.Name
+			td.Ref = alias + "." + td.Name
 		}
+		typeByName[typeName] = td
 	}
 
 	return &imports{
-		TypeRefByTypeName: typeRefByTypeName,
-		ImportLines:       importLines,
+		TypeByName:  typeByName,
+		ImportLines: importLines,
 	}, nil
 }
 

v2alpha/srv/srv.gotemplate

@@ -1,5 +1,6 @@
 {{define "service"}}
 {{- $Imps := .Imps -}}
+// Package {{.Manifest.Package}} provides types for the {{quote .Manifest.ServiceType}} service.
 package {{.Manifest.Package}}
 
 import (
@@ -9,7 +10,6 @@ import (
 )
 
 const ServiceType = {{quote .Manifest.ServiceType}}
-
 {{range .SCPD.SortedActions}}
 {{- template "action" args "Action" . "Imps" $Imps}}
 {{end}}
@@ -17,21 +17,31 @@ const ServiceType = {{quote .Manifest.ServiceType}}
 
 {{define "action"}}
 {{- $Imps := .Imps}}
+{{- $soapActionType := index $Imps.TypeByName "SOAPActionInterface"}}
+// {{.Action.Name}} provides request and response for the action.
+//
+// ServiceType implements {{$soapActionType.AbsRef}}, self-describing the SOAP action.
 type {{.Action.Name}} struct{
   Request {{.Action.Name}}Request
   Response {{.Action.Name}}Response
 }
 
-var _ {{index $Imps.TypeRefByTypeName "SOAPActionInterface"}} = &{{.Action.Name}}{{"{}"}}
+var _ {{$soapActionType.Ref}} = &{{.Action.Name}}{{"{}"}}
 
+// ServiceType implements {{$soapActionType.AbsRef}}.
 func (a *{{.Action.Name}}) ServiceType() string { return ServiceType }
+// ActionName implements {{$soapActionType.AbsRef}}.
 func (a *{{.Action.Name}}) ActionName() string { return {{quote .Action.Name}} }
+// RefRequest implements {{$soapActionType.AbsRef}}.
 func (a *{{.Action.Name}}) RefRequest() any { return &a.Request }
+// RefResponse implements {{$soapActionType.AbsRef}}.
 func (a *{{.Action.Name}}) RefResponse() any { return &a.Response }
 
+// {{.Action.Name}}Request contains the "in" args for the {{quote .Action.Name}} action.
 type {{.Action.Name}}Request struct
 {{- template "args" args "Args" .Action.InArgs "Imps" $Imps}}
 
+// {{.Action.Name}}Response contains the "out" args for the {{quote .Action.Name}} action.
 type {{.Action.Name}}Response struct
 {{- template "args" args "Args" .Action.OutArgs "Imps" $Imps}}
 {{- end}}
@@ -40,7 +50,8 @@ type {{.Action.Name}}Response struct
 {{- $Imps := .Imps -}}
 { {{- with .Args}}
 {{- range .}}
-  {{.Name}} {{index $Imps.TypeRefByTypeName .RelatedStateVariable.DataType}}
+{{- $fieldType := index $Imps.TypeByName .RelatedStateVariable.DataType}}
+  {{.Name}} {{$fieldType.Ref}}
 {{- end}}
 {{end -}} }
 {{- end}}