Generate documentation comments from service template.

This commit is contained in:
John Beisley 2022-06-08 18:13:28 +01:00
parent 91c176e495
commit 3db7296aeb
2 changed files with 37 additions and 11 deletions

View File

@ -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
}

View File

@ -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}}