chore: add comments

Signed-off-by: Binbin Li <[email protected]>

core/api.go

@@ -23,7 +23,11 @@ import (
 
 // VerifyParameters describes the artifact validation parameters
 type VerifyParameters struct {
-	Subject        string   `json:"subjectReference"`
+	// SubjectArtifact is the artifact to be validated. Required.
+	SubjectArtifact string `json:"subjectArtifact"`
+	// ReferenceTypes is a list of reference types that should be verified in
+	// associated artifacts. Empty list means all artifacts should be verified.
+	// Optional.
 	ReferenceTypes []string `json:"referenceTypes,omitempty"`
 }
 

internal/common/manifest.go

@@ -19,7 +19,8 @@ import (
 	oci "github.com/opencontainers/image-spec/specs-go/v1"
 )
 
-// ReferenceManifest describes an artifact manifest
+// ReferenceManifest describes an artifact manifest in
+// `application/vnd.oci.artifact.manifest.v1+json` mediatype.
 type ReferenceManifest struct {
 	MediaType    string            `json:"mediaType"`
 	ArtifactType string            `json:"artifactType,omitempty"`

internal/common/reference.go

@@ -20,15 +20,21 @@ import (
 	v1 "github.com/opencontainers/image-spec/specs-go/v1"
 )
 
-// Reference describes an image reference identifier that includes properties like digest, tag
+// Reference describes an image reference identifier that includes properties like digest, tag.
 type Reference struct {
-	Path       string
-	Digest     digest.Digest
-	Tag        string
-	Original   string
+	// Path is the repository path of the artifact.
+	Path string
+	// Digest is the digest of the artifact.
+	Digest digest.Digest
+	// Tag is the tag of the artifact.
+	Tag string
+	// Original is the original string representation of the reference.
+	Original string
+	// Descriptor is the descriptor of the artifact.
 	Descriptor v1.Descriptor
 }
 
+// String returns the original string representation of the reference.
 func (ref Reference) String() string {
 	return ref.Original
 }

internal/constants/constants.go

@@ -16,6 +16,9 @@ limitations under the License.
 package constants
 
 const (
+	// Name and Type are the keys to identify a plugin.
+	// Name specifies a plugin's unique identifier, allowing multiple plugins of the same type.
 	Name = "name"
+	// Type represents a plugin type, which defines the plugin kind.
 	Type = "type"
 )

internal/errors/types.go

@@ -62,6 +62,17 @@ func (ec ErrorCode) ErrorCode() ErrorCode {
 	return ec
 }
 
+// Error returns the ID/Value
+func (ec ErrorCode) Error() string {
+	// NOTE(stevvooe): Cannot use message here since it may have unpopulated args.
+	return strings.ToLower(strings.Replace(ec.String(), "_", " ", -1))
+}
+
+// String returns the canonical identifier for this error code.
+func (ec ErrorCode) String() string {
+	return ec.Descriptor().Value
+}
+
 // Descriptor returns the descriptor for the error code.
 func (ec ErrorCode) Descriptor() ErrorDescriptor {
 	d, ok := errorCodeToDescriptors[ec]

internal/errors/types_test.go

@@ -61,6 +61,12 @@ func TestRegisterPanic(t *testing.T) {
 	})
 }
 
+func TestErrorCode_Error(t *testing.T) {
+	if err := testEC.Error(); err != "test error code 1" {
+		t.Fatalf("expected: %s, got: %s", "test error code 1", err)
+	}
+}
+
 func TestErrorCode(t *testing.T) {
 	ec := ErrorCode(1)
 	if ec.ErrorCode() != 1 {

plugin/policyenforcer/api.go

@@ -24,25 +24,34 @@ import (
 // ValidationResult aggregates verifier reports and the final verification
 // result evaluated by the policy enforcer.
 type ValidationResult struct {
-	IsSuccess       bool                        `json:"isSuccess,omitempty"`
+	// IsSuccess indicates whether the verification is successful. Optional.
+	// This field is optional because the policy enforcer may not be required to
+	// evaluate the reports.
+	IsSuccess bool `json:"isSuccess,omitempty"`
+	// ArtifactReports is reports of verifying associated artifacts. Required.
 	ArtifactReports []*ArtifactValidationReport `json:"artifactReports"`
 }
 
 // ArtifactValidationReport describes the results of verifying an artifact and its
 // nested artifacts by available verifiers.
 type ArtifactValidationReport struct {
-	Subject               string                      `json:"subject"`
-	ReferenceDigest       string                      `json:"referenceDigest"`
-	ArtifactType          string                      `json:"artifactType"`
-	VerifierReports       []verifier.VerifierResult   `json:"verifierReports"`
+	// Subject is the artifact that is verified. Required.
+	Subject string `json:"subject"`
+	// ReferenceDigest is the digest of the artifact that is verified. Required.
+	ReferenceDigest string `json:"referenceDigest"`
+	// ArtifactType is the media type of the artifact that is verified. Required.
+	ArtifactType string `json:"artifactType"`
+	// VerifierReports is reports of verifying the artifact by matching verifiers. Required.
+	VerifierReports []verifier.VerifierResult `json:"verifierReports"`
+	// NestedArtifactReports is reports of verifying nested artifacts. Required.
 	NestedArtifactReports []*ArtifactValidationReport `json:"nestedReports"`
 }
 
 // PolicyEnforcer is an interface with methods that represents policy decisions.
 type PolicyEnforcer interface {
-	// ErrorToVerifyResult converts an error to a properly formatted verify result
+	// ErrorToVerifyResult converts an error to a properly formatted verify result.
 	ErrorToVerifyResult(ctx context.Context, subjectRefString string, verifyError error) ValidationResult
-	// EvaluateVerifierReport determines the final outcome of verification that is constructed using the results from
-	// individual verifications
+	// EvaluateVerifierReport determines the final outcome of verification that
+	// is constructed using the results from individual verifications.
 	EvaluateVerifierReport(ctx context.Context, verifierReports []*ArtifactValidationReport) bool
 }

plugin/policyenforcer/factory.go

@@ -24,9 +24,13 @@ var RegisteredPolicyEnforcers = make(map[string]PolicyEnforcerFactory)
 
 // PolicyEnforcerConfig represents the configuration of a policy plugin
 type PolicyEnforcerConfig struct {
-	Name       string                 `json:"name"`
-	Type       string                 `json:"type"`
-	Parameters map[string]interface{} `json:"parameters"`
+	// Name is unique identifier of a policy enforcer. Required.
+	Name string `json:"name"`
+	// Type of the policy enforcer. Note: there could be multiple policy enforcers
+	// of the same type with different names. Required.
+	Type string `json:"type"`
+	// Parameters of the policy enforcer. Optional.
+	Parameters map[string]interface{} `json:"parameters,omitempty"`
 }
 
 // PolicyEnforcerFactory is an interface that defines create method to create a

plugin/store/api.go

@@ -23,9 +23,11 @@ import (
 	"github.com/ratify-project/ratify-go/internal/common"
 )
 
-// ListReferrersResult represents the result of ListReferrers API
+// ListReferrersResult represents a paginated result of ListReferrers API.
 type ListReferrersResult struct {
+	// Referrers is the list of referrers in the current page.
 	Referrers []oci.Descriptor
+	// NextToken is the token to get the next page of results.
 	NextToken string
 }
 
@@ -36,6 +38,8 @@ type ReferrerStore interface {
 
 	// ListReferrers returns the immediate set of supply chain artifacts for the given subject
 	// represented as artifact manifests.
+	// Note: This API supports pagination. The nextToken is used to get the next page of results.
+	// The nextToken is supposed to be empty if there are no more results.
 	ListReferrers(ctx context.Context, subjectReference common.Reference, artifactTypes []string, nextToken string) (ListReferrersResult, error)
 
 	// GetBlobContent returns the blob with the given digest.

plugin/store/factory.go

@@ -24,9 +24,13 @@ var RegisteredStores = make(map[string]StoreFactory)
 
 // StoreConfig represents the configuration of a store.
 type StoreConfig struct {
-	Name       string                 `json:"name"`
-	Type       string                 `json:"type"`
-	Parameters map[string]interface{} `json:"parameters"`
+	// Name is unique identifier of the store. Required.
+	Name string `json:"name"`
+	// Type of the store. Required.
+	// Note: there could be multiple stores of the same type with different names.
+	Type string `json:"type"`
+	// Parameters of the store. Optional.
+	Parameters map[string]interface{} `json:"parameters,omitempty"`
 }
 
 // StoreFactory is an interface that defines create method to create a store

plugin/verifier/factory.go

@@ -22,10 +22,14 @@ var RegisteredVerifiers = make(map[string]VerifierFactory)
 
 // VerifierConfig represents the configuration of a verifier.
 type VerifierConfig struct {
-	Name          string                 `json:"name"`
-	Type          string                 `json:"type"`
-	ArtifactTypes []string               `json:"artifactTypes"`
-	Parameters    map[string]interface{} `json:"parameters"`
+	// Name is the unique identifier of the verifier. Required.
+	Name string `json:"name"`
+	// Type is the type of the verifier. Note: there could be multiple verifiers of the same type with different names. Required.
+	Type string `json:"type"`
+	// ArtifactTypes is the list of artifact types that the verifier can verify. Required.
+	ArtifactTypes []string `json:"artifactTypes"`
+	// Parameters is additional parameters of the verifier. Optional.
+	Parameters map[string]interface{} `json:"parameters,omitempty"`
 }
 
 // VerifierFactory is an interface that defines create method to create a verifier

plugin/verifier/result.go

@@ -19,13 +19,21 @@ import "github.com/ratify-project/ratify-go/internal/errors"
 
 // VerifierResult defines the verification result that a verifier plugin must return.
 type VerifierResult struct {
-	IsSuccess    bool        `json:"isSuccess"`
-	Message      string      `json:"message"`
-	ErrorReason  string      `json:"errorReason,omitempty"`
-	Remediation  string      `json:"remediation,omitempty"`
-	VerifierName string      `json:"verifierName,omitempty"`
-	VerifierType string      `json:"verifierType,omitempty"`
-	Extensions   interface{} `json:"extensions"`
+	// IsSuccess indicates whether the verification was successful or not. Required.
+	IsSuccess bool `json:"isSuccess"`
+	// Message is a human-readable message that describes the verification result. Required.
+	Message string `json:"message"`
+	// VerifierName is the name of the verifier that produced this result. Required.
+	VerifierName string `json:"verifierName"`
+	// VerifierType is the type of the verifier that produced this result. Required.
+	VerifierType string `json:"verifierType"`
+	// ErrorReason is a machine-readable reason for the verification failure. Optional.
+	ErrorReason string `json:"errorReason,omitempty"`
+	// Remediation is a machine-readable remediation for the verification failure. Optional.
+	Remediation string `json:"remediation,omitempty"`
+	// Extensions is additional information that can be used to provide more
+	// context about the verification result. Optional.
+	Extensions interface{} `json:"extensions,omitempty"`
 }
 
 // NewVerifierResult creates a new VerifierResult object with the given parameters.