chore: improve docs around remote claims related configuration for factor and options

- improving the documentation and grouping around remote claims builder's configuration and options, reducing the cognitive load (what is and what isn't related to themis' remote claims builder can be confusing and hard to follow)

Author: denopink

token/claimBuilder.go

@@ -117,8 +117,7 @@ func (nc nonceClaimBuilder) AddClaims(_ context.Context, r *Request, target map[
 	return nil
 }
 
-// remoteClaimBuilder invokes a remote system to obtain claims.  The metadata from a token request
-// is passed as the payload.
+// remoteClaimBuilder invokes a remote system to obtain claims.
 type remoteClaimBuilder struct {
 	endpoint endpoint.Endpoint
 	url      string

token/factory.go

@@ -30,17 +30,15 @@ type Request struct {
 	// but will not override time-based claims such as nbf or exp.
 	Claims map[string]interface{}
 
-	// Metadata holds non-claim information about the request, usually garnered from the original HTTP request.  This
-	// metadata is available to lower levels of infrastructure used by the Factory.
-	Metadata map[string]interface{}
 
-	// PathWildCards holds non-claim information about the request, usually garnered from the original HTTP request.  This
-	// PathWildCards is available to remote claim builders
-	PathWildCards map[string]any
 
 	// TLS represents the state of any underlying TLS connection.
 	// For non-tls connections, this field is unset.
 	TLS *tls.ConnectionState
+
+	// The following fields are for remote claims' requests.
+	Metadata      map[string]any // Metadata is the request payload.
+	PathWildCards map[string]any // PathWildCards are the request path wildcards.
 }
 
 // NewRequest returns an empty, fully initialized token Request

token/options.go

@@ -201,13 +201,6 @@ type Options struct {
 	// or statically from configuration.  For special processing around the partner id, set the PartnerID field.
 	Claims []Value
 
-	// Metadata describes non-claim data, which can be statically configured or supplied via a request
-	Metadata []Value
-
-	// PathWildCards holds non-claim information about the request, usually garnered from the original HTTP request.  This
-	// PathWildCards is available to remote claim builders.
-	PathWildCards []Value
-
 	// PartnerID is the optional partner id configuration.  If unset, no partner id processing is
 	// performed, though a partner id may still be configured as part of the claims.
 	PartnerID *PartnerID
@@ -238,4 +231,8 @@ type Options struct {
 	// and returns a set of claims to be merged into tokens returned by the Factory.  Returned
 	// claims from the remote system do not override claims configured on the Factory.
 	Remote *RemoteClaims
+
+	// The following options are for remote claims' requests.
+	Metadata      []Value // Metadata describes the non-claim request payload, which can be statically configured or supplied via a request.
+	PathWildCards []Value // PathWildCards are the request path wildcards, which can be statically configured or supplied via a HTTP request.
 }