fix typos + some doc

cmds/ocm/commands/ocmcmds/common/addhdlrs/comp/components.go

@@ -23,9 +23,9 @@ func ProcessComponents(ctx clictx.Context, ictx inputs.Context, repo ocm.Reposit
 
 	for _, elem := range elems {
 		if r, ok := elem.Spec().(*ResourceSpec); ok {
-			list.Add(addhdlrs.ValdateElementSpecIdentities("resource", elem.Source().String(), generics.ConvertSliceTo[addhdlrs.ElementSpec](r.Resources)))
-			list.Add(addhdlrs.ValdateElementSpecIdentities("source", elem.Source().String(), generics.ConvertSliceTo[addhdlrs.ElementSpec](r.Sources)))
-			list.Add(addhdlrs.ValdateElementSpecIdentities("reference", elem.Source().String(), generics.ConvertSliceTo[addhdlrs.ElementSpec](r.References)))
+			list.Add(addhdlrs.ValidateElementSpecIdentities("resource", elem.Source().String(), generics.ConvertSliceTo[addhdlrs.ElementSpec](r.Resources)))
+			list.Add(addhdlrs.ValidateElementSpecIdentities("source", elem.Source().String(), generics.ConvertSliceTo[addhdlrs.ElementSpec](r.Sources)))
+			list.Add(addhdlrs.ValidateElementSpecIdentities("reference", elem.Source().String(), generics.ConvertSliceTo[addhdlrs.ElementSpec](r.References)))
 		}
 	}
 	if err := list.Result(); err != nil {

cmds/ocm/commands/ocmcmds/common/addhdlrs/interface.go

@@ -16,20 +16,28 @@ import (
 	"github.com/open-component-model/ocm/pkg/generics"
 )
 
+// ResourceInput describe the source for the content of
+// a content based element (sources or resources).
+// It is either an input or access specification.
 type ResourceInput struct {
 	Access *cpi.GenericAccessSpec `json:"access"`
 	// Input  *inputs.BlobInput                `json:"input,omitempty"`
 	Input *inputs.GenericInputSpec `json:"input,omitempty"`
 }
 
+// ElementSpecHandler is the interface for a handler
+// responsible to handle a dedicated kind of element specification.
 type ElementSpecHandler interface {
 	Key() string
 	RequireInputs() bool
 	Decode(data []byte) (ElementSpec, error)
 }
 
 type ElementSource interface {
+	// Origin provides access to the source
+	// specification used to provide elements.
 	Origin() SourceInfo
+	// Get provides access to the content of the element source.
 	Get() (string, error)
 }
 
@@ -76,6 +84,9 @@ func (s *sourceInfo) Id() string {
 	return id
 }
 
+// ElementSpec is the specification of
+// the model element. It provides access to
+// common attributes, like the identity.
 type ElementSpec interface {
 	GetName() string
 	GetVersion() string
@@ -85,11 +96,21 @@ type ElementSpec interface {
 	Validate(ctx clictx.Context, input *ResourceInput) error
 }
 
+// Element is the abstraction over model elements handled by
+// the add handler, for example, resources, sources, references or complete
+// component versions.
 type Element interface {
+	// Source provides info about the source the element has been
+	// derived from. (for example a component.yaml or resources.yaml).
 	Source() SourceInfo
+	// Spec provides access to the element specification.
 	Spec() ElementSpec
+	// Type is used for types elements, like sources and resources.
 	Type() string
+	// Data provides access to the element descriptor representation.
 	Data() []byte
+	// Input provides access to the underlying data specification.
+	// It is either an access specification or an input specification.
 	Input() *ResourceInput
 }
 

cmds/ocm/commands/ocmcmds/common/addhdlrs/utils.go

@@ -37,7 +37,7 @@ func ProcessDescriptions(ctx clictx.Context, printer common2.Printer, templ temp
 		}
 		elems = append(elems, tmp...)
 	}
-	err := ValdateElementIdentities(h.Key(), elems)
+	err := ValidateElementIdentities(h.Key(), elems)
 	if err != nil {
 		return nil, nil, err
 	}
@@ -283,7 +283,7 @@ func Validate(r *ResourceInput, ctx inputs.Context, inputFilePath string) error
 	return allErrs.ToAggregate()
 }
 
-func ValdateElementIdentities(kind string, elems []Element) error {
+func ValidateElementIdentities(kind string, elems []Element) error {
 	list := errors.ErrList()
 	ids := map[string]SourceInfo{}
 	for _, r := range elems {
@@ -302,7 +302,11 @@ func ValdateElementIdentities(kind string, elems []Element) error {
 	return list.Result()
 }
 
-func ValdateElementSpecIdentities(kind string, src string, elems []ElementSpec) error {
+// ValidateElementSpecIdentities validate the element specifications
+// taken from some source (for example a resources.yaml or components.yaml).
+// The parameter src somehow identifies the element source, for example
+// the path of the parsed file.
+func ValidateElementSpecIdentities(kind string, src string, elems []ElementSpec) error {
 	list := errors.ErrList()
 	ids := map[string]int{}
 	for i, r := range elems {

pkg/contexts/ocm/compdesc/meta/v1/types.go

@@ -15,8 +15,18 @@ import (
 	"github.com/open-component-model/ocm/pkg/errors"
 )
 
+// These constants describe identity attributes predefined by the
+// model used to identify elements (resources, sources and references)
+// in a component version.
 const (
-	SystemIdentityName    = "name"
+	// SystemIdentityName is the name attribute of an element in
+	// a component version. It is always present.
+	SystemIdentityName = "name"
+	// SystemIdentityVersion is the version attribute optionally
+	// added to the identity of an element in a component version.
+	// It is required, if the name and the other explicitly defined
+	// extra identity attributes are not unique for a dedicated
+	// kind of element in the context of a component version.
 	SystemIdentityVersion = "version"
 )