proxy: imp docs

proxy/upstreams.go

@@ -13,10 +13,6 @@ import (
 	"golang.org/x/exp/slices"
 )
 
-// errWrongUpstreamSpecs is returned by [ParseUpstreamsConfig] when upstreams
-// configuration is invalid.
-const errWrongUpstreamSpecs errors.Error = "wrong upstream specification"
-
 // UpstreamConfig is a wrapper for a list of default upstreams, a map of
 // reserved domains and corresponding upstreams.
 type UpstreamConfig struct {
@@ -38,9 +34,10 @@ type UpstreamConfig struct {
 // type check
 var _ io.Closer = (*UpstreamConfig)(nil)
 
-// ParseUpstreamsConfig returns UpstreamConfig and error if upstreams
-// configuration is invalid.  It also skips empty lines and comments (lines
-// begining with `#`).
+// ParseUpstreamsConfig returns an UpstreamConfig and nil error if the upstream
+// configuration is valid.  Otherwise returns a partially filled UpstreamConfig
+// and wrapped error containing lines with errors.  It also skips empty lines
+// and comments (lines starting with `#`).
 //
 // # Simple upstreams
 //
@@ -214,15 +211,15 @@ func (p *configParser) parseLine(idx int, confLine string) (err error) {
 
 // splitConfigLine parses upstream configuration line and returns list upstream
 // addresses (one or many), list of domains for which this upstream is reserved
-// (may be nil) or error if something went wrong.
+// (may be nil).  It returns an error if the upstream format is incorrect.
 func splitConfigLine(confLine string) (upstreams, domains []string, err error) {
 	if !strings.HasPrefix(confLine, "[/") {
 		return []string{confLine}, nil, nil
 	}
 
 	domainsLine, upstreamsLine, found := strings.Cut(confLine[len("[/"):], "/]")
 	if !found || upstreamsLine == "" {
-		return nil, nil, errWrongUpstreamSpecs
+		return nil, nil, errors.Error("wrong upstream format")
 	}
 
 	// split domains list