docu + review comments

api/ocm/plugin/descriptor/descriptor.go

@@ -259,9 +259,16 @@ func (d TransferHandlerDescriptor) GetQuestion(name string) *QuestionDescriptor
 }
 
 type QuestionDescriptor struct {
-	Question    string    `json:"question"`
-	Description string    `json:"description,omitempty"`
-	Labels      *[]string `json:"labels,omitempty"`
+	// Question is the name of the question the plugin can answer.
+	// Possible types and their meaning is described by the
+	// variable common.TransferHandlerQuestions.
+	Question    string `json:"question"`
+	Description string `json:"description,omitempty"`
+	// Labels described the list of labels passed to the
+	// plugin if they exist. If not specified all labels
+	// are transferred, if an empty list is specified no
+	// labels are transferred to the plugin command.
+	Labels *[]string `json:"labels,omitempty"`
 }
 
 ////////////////////////////////////////////////////////////////////////////////

api/ocm/plugin/internal/transfer.go

@@ -52,22 +52,30 @@ type Resolution struct {
 	RepositorySpec *ocm.GenericRepositorySpec `json:"repository,omitempty"`
 	// TransferHandler is the handler identity according to the transfer handler
 	// name scheme.
-	TransferHandler string           `json:"transferHandler,omitempty"`
+	TransferHandler string `json:"transferHandler,omitempty"`
+	// TransferOptions may describe modified options used for sub-sequent
+	// transfers.
 	TransferOptions *TransferOptions `json:"transferOptions,omitempty"`
 }
 
+// DecisionRequestResult is the structure of the answer
+// the plugin has to return for a question.
 type DecisionRequestResult struct {
 	Error      string      `json:"error,omitempty"`
 	Decision   bool        `json:"decision"`
 	Resolution *Resolution `json:"resolution,omitempty"`
 }
 
+// ComponentVersionQuestion describes the question arguments
+// given for a component version related question.
 type ComponentVersionQuestion struct {
 	Source  SourceComponentVersion `json:"source"`
 	Target  TargetRepositorySpec   `json:"target"`
 	Options TransferOptions        `json:"options"`
 }
 
+// ComponentReferenceQuestion  describes the question arguments
+// given for a component version reference related question.
 type ComponentReferenceQuestion struct {
 	Source SourceComponentVersion `json:"source"`
 	Target TargetRepositorySpec   `json:"target"`
@@ -84,6 +92,8 @@ type Artifact struct {
 	AccessInfo UniformAccessSpecInfo `json:"accessInfo"`
 }
 
+// ArtifactQuestion  describes the question arguments
+// given for an artifact related question.
 type ArtifactQuestion struct {
 	Source   SourceComponentVersion `json:"source"`
 	Artifact Artifact               `json:"artifact"`

api/ocm/plugin/ppi/interface.go

@@ -220,17 +220,38 @@ type Command interface {
 	Command() *cobra.Command
 }
 
+// TransferHandler is the support interface
+// for implementing a transfer handler for the plugin support
+// library.
+// There is a standard implementation NewTransferHandler.
 type TransferHandler interface {
 	GetName() string
 	GetDescription() string
 	GetQuestions() []DecisionHandler
 }
 
+// DecisionHandler is the support interface for implementing
+// the answer to a question used for the TransferHandler.
+// A base implementation providing the non-functional attributues
+// cane be obtained by NewDecisionHandlerBase.
 type DecisionHandler interface {
+	// GetQuestion returns the name of the question answered by this handler
+	// (see common.TransferHandlerQuestions).
 	GetQuestion() string
+
 	GetDescription() string
+	// GetLabels returns the list of labels, which should be passed
+	// to the transfer handler. If nothing is specified all labels
+	// are transferred, if an empty list is given no label is handed over
+	// to the plugin command.
 	GetLabels() *[]string
 
+	// DecideOn implements the calculation of the answer to
+	// the question.The given question contains the arguments for
+	// the questions. There are three kinds of arguments:
+	// ArtifactQuestion, ComponentVersionQuestion and ComponentReferenceQuestion.
+	// TransferHandlerQuestions maps the question name to the used
+	// argument type.
 	DecideOn(p Plugin, question interface{}) (bool, error)
 }
 

api/ocm/plugin/ppi/utils.go

@@ -158,6 +158,10 @@ func (t *transferHandler) RegisterDecision(h DecisionHandler) error {
 	return nil
 }
 
+// DecisionHandlerBase provides access to the
+// non-functional attributes of a DecisionHandler.
+// It can be created with NewDecisionHandlerBase and
+// embedded into the final DecisionHandler implementation.
 type DecisionHandlerBase struct {
 	question    string
 	description string

api/tech/access.go

@@ -1,11 +1,11 @@
 package tech
 
 // UniformAccessSpecInfo describes a rough uniform specification for
-// an access location or an accessed object. It not necessarily
-// provided the exact access information required to technically
+// an access location or an accessed object. It does not necessarily
+// provide the exact access information required to technically
 // access the object, but just some general information usable
 // independently of the particular technical access specification
-// to figure aut some general information in a formal way about the access.
+// to figure out some general information in a formal way about the access.
 type UniformAccessSpecInfo struct {
 	Kind string `json:"kind"`
 	Host string `json:"host,omitempty"`

cmds/transferplugin/transferhandlers/demo_test.go

@@ -4,12 +4,14 @@ import (
 	"bytes"
 	"encoding/json"
 
-	"github.com/mandelsoft/goutils/sliceutils"
 	. "github.com/mandelsoft/goutils/testutils"
-	"github.com/mandelsoft/vfs/pkg/osfs"
-	"github.com/mandelsoft/vfs/pkg/vfs"
 	. "github.com/onsi/ginkgo/v2"
 	. "github.com/onsi/gomega"
+
+	"github.com/mandelsoft/goutils/sliceutils"
+	"github.com/mandelsoft/vfs/pkg/osfs"
+	"github.com/mandelsoft/vfs/pkg/vfs"
+
 	"ocm.software/ocm/api/ocm"
 	metav1 "ocm.software/ocm/api/ocm/compdesc/meta/v1"
 	v2 "ocm.software/ocm/api/ocm/compdesc/versions/v2"
@@ -23,7 +25,7 @@ import (
 )
 
 var _ = Describe("Test Environment", func() {
-	It("", func() {
+	It("runs a demo question", func() {
 		var stdout bytes.Buffer
 		var stderr bytes.Buffer