Attempt to tidy generated documentation.

cmd/specgen/pkgtmpl.go

@@ -34,48 +34,32 @@ type {{$srvIdent}} struct {
 
 {{range .SCPD.Actions}}{{/* loops over *SCPDWithURN values */}}
 
+{{$inargs := .InputArguments}}{{$outargs := .OutputArguments}}
 // {{.Name}} action.
-// Arguments:
-//{{range .Arguments}}{{if .IsInput}}
-// * {{.Name}}: {{$v := $srv.SCPD.GetStateVariable .RelatedStateVariable}}
-{{if $v}}// (related state variable: {{$v.Name}})
-// - {{if $v.AllowedValueRange}}allowed range: {{$v.AllowedValueRange.Minimum}} to {{$v.AllowedValueRange.Maximum}}{{end}}
-// - {{if $v.AllowedValues}}allowed values:
-// {{range $i, $val := $v.AllowedValues}}{{if $i}}|{{end}}{{$val}}{{end}}{{end}}
-//{{else}}
-// (unknown){{end}}
-//{{end}}{{end}}
 //
-// Return values:
+// {{if $inargs}}Arguments:{{range $inargs}}{{$argWrap := $srv.WrapArgument .}}
-//{{range .Arguments}}{{if .IsOutput}}
+// * {{.Name}}: {{$argWrap.Document}}
-// * {{.Name}}: {{$v := $srv.SCPD.GetStateVariable .RelatedStateVariable}}
-{{if $v}}// (related state variable: {{$v.Name}})
-// - {{if $v.AllowedValueRange}}allowed range: {{$v.AllowedValueRange.Minimum}} to {{$v.AllowedValueRange.Maximum}}{{end}}
-// - {{if $v.AllowedValues}}allowed values:
-// {{range $i, $val := $v.AllowedValues}}{{if $i}}|{{end}}{{$val}}{{end}}{{end}}
-//{{else}}
-// (unknown){{end}}
 //{{end}}{{end}}
-func (client *{{$srvIdent}}) {{.Name}}({{range .Arguments}}{{if .IsInput}}
+// {{if $outargs}}Return values:{{range $outargs}}{{$argWrap := $srv.WrapArgument .}}
-	{{$argWrap := $srv.Argument .}}{{$argWrap.AsParameter}},{{end}}{{end}}
+// * {{.Name}}: {{$argWrap.Document}}
-) ({{range .Arguments}}{{if .IsOutput}}
+//{{end}}{{end}}
-	{{$argWrap := $srv.Argument .}}{{$argWrap.AsParameter}},{{end}}{{end}}
+func (client *{{$srvIdent}}) {{.Name}}({{range $inargs}}{{/*
-	err error,
+*/}}{{$argWrap := $srv.WrapArgument .}}{{$argWrap.AsParameter}}, {{end}}{{/*
-) {
+*/}}) ({{range $outargs}}{{/*
+*/}}{{$argWrap := $srv.WrapArgument .}}{{$argWrap.AsParameter}}, {{end}} err error) {
 	// Request structure.
 	var request struct {{"{"}}{{range .Arguments}}{{if .IsInput}}{{.Name}} string
 {{end}}{{end}}}
 	// BEGIN Marshal arguments into request.
-{{range .Arguments}}{{if .IsInput}}{{$argWrap := $srv.Argument .}}
+{{range $inargs}}{{$argWrap := $srv.WrapArgument .}}
 	if request.{{.Name}}, err = {{$argWrap.Marshal}}; err != nil {
 		return
-	}
+	}{{end}}
-{{end}}{{end}}
 	// END Marshal arguments into request.
 
 	// Response structure.
-	var response struct {{"{"}}{{range .Arguments}}{{if .IsOutput}}{{.Name}} string
+	var response struct {{"{"}}{{range $outargs}}{{.Name}} string
-{{end}}{{end}}}
+{{end}}}
 
 	// Perform the SOAP call.
 	if err = client.SOAPClient.PerformAction({{$srv.URNParts.Const}}, "{{.Name}}", &request, &response); err != nil {
@@ -83,11 +67,10 @@ func (client *{{$srvIdent}}) {{.Name}}({{range .Arguments}}{{if .IsInput}}
 	}
 
 	// BEGIN Unmarshal arguments from response.
-{{range .Arguments}}{{if .IsOutput}}{{$argWrap := $srv.Argument .}}
+{{range $outargs}}{{$argWrap := $srv.WrapArgument .}}
 	if {{.Name}}, err = {{$argWrap.Unmarshal "response"}}; err != nil {
 		return
-	}
+	}{{end}}
-{{end}}{{end}}
 	// END Unmarshal arguments from response.
 	return
 }

cmd/specgen/specgen.go

@@ -215,7 +215,7 @@ type SCPDWithURN struct {
 	SCPD *scpd.SCPD
 }
 
-func (s *SCPDWithURN) Argument(arg scpd.Argument) (*argumentWrapper, error) {
+func (s *SCPDWithURN) WrapArgument(arg scpd.Argument) (*argumentWrapper, error) {
 	relVar := s.SCPD.GetStateVariable(arg.RelatedStateVariable)
 	if relVar == nil {
 		return nil, fmt.Errorf("no such state variable: %q, for argument %q", arg.RelatedStateVariable, arg.Name)
@@ -241,6 +241,27 @@ func (arg *argumentWrapper) AsParameter() string {
 	return fmt.Sprintf("%s %s", arg.Name, arg.conv.ExtType)
 }
 
+func (arg *argumentWrapper) Document() string {
+	relVar := arg.relVar
+	if rng := relVar.AllowedValueRange; rng != nil {
+		var parts []string
+		if rng.Minimum != "" {
+			parts = append(parts, fmt.Sprintf("minimum=%s", rng.Minimum))
+		}
+		if rng.Maximum != "" {
+			parts = append(parts, fmt.Sprintf("maximum=%s", rng.Maximum))
+		}
+		if rng.Step != "" {
+			parts = append(parts, fmt.Sprintf("step=%s", rng.Step))
+		}
+		return "allowed value range: " + strings.Join(parts, ", ")
+	}
+	if len(relVar.AllowedValues) != 0 {
+		return "allowed values: " + strings.Join(relVar.AllowedValues, ", ")
+	}
+	return ""
+}
+
 func (arg *argumentWrapper) Marshal() string {
 	return fmt.Sprintf("soap.Marshal%s(%s)", arg.conv.FuncSuffix, arg.Name)
 }

scpd/scpd.go

@@ -66,6 +66,28 @@ func (action *Action) clean() {
 	}
 }
 
+func (action *Action) InputArguments() []*Argument {
+	var result []*Argument
+	for i := range action.Arguments {
+		arg := &action.Arguments[i]
+		if arg.IsInput() {
+			result = append(result, arg)
+		}
+	}
+	return result
+}
+
+func (action *Action) OutputArguments() []*Argument {
+	var result []*Argument
+	for i := range action.Arguments {
+		arg := &action.Arguments[i]
+		if arg.IsOutput() {
+			result = append(result, arg)
+		}
+	}
+	return result
+}
+
 type Argument struct {
 	Name                 string `xml:"name"`
 	Direction            string `xml:"direction"`            // in|out