docs(credential): add documention comment

axone-protocol · Sep 3, 2024 · 227045b · 227045b
1 parent 748e7a4
commit 227045b
Show file tree

Hide file tree

Showing 2 changed files with 31 additions and 14 deletions.
diff --git a/credential/generate.go b/credential/generate.go
@@ -18,14 +18,26 @@ import (
 //go:embed template/vc-gov-tpl.jsonld
 var governanceTemplate string
 
+// Generator is a verifiable credential generator.
 type Generator struct {
 	vc        Descriptor
 	signer    verifiable.Signer
 	signerDID string
 	parser    *credentialParser
 }
 
-func NewGenerator(descriptor Descriptor) *Generator {
+// New allow to generate a verifiable credential with the given credential descriptor.
+// Example:
+//
+//	vc, err := credential.New(
+//	    NewGovernanceVC().
+//	        WithDatasetDID("did:key:...").
+//	        WithGovAddr("axone1234..."),
+//	).
+//	WithParser(parser).
+//	WithSignature(signer, "did:key:..."). // Signature is optional and generate a not signed VC if not provided.
+//	Generate()
+func New(descriptor Descriptor) *Generator {
 	return &Generator{
 		vc: descriptor,
 	}
@@ -73,6 +85,7 @@ func (generator *Generator) Generate() (*verifiable.Credential, error) {
 	return cred, nil
 }
 
+// Descriptor is an interface representing the description of a verifiable credential.
 type Descriptor interface {
 	issuedAt() *time.Time
 	generate() (*bytes.Buffer, error)
@@ -81,21 +94,17 @@ type Descriptor interface {
 
 var _ Descriptor = NewGovernanceVC()
 
+// GovernanceVCDescriptor is a descriptor for a governance verifiable credential.
 type GovernanceVCDescriptor struct {
 	id           string
 	datasetDID   string
 	govAddr      string
 	issuanceDate *time.Time
 }
 
-func (g *GovernanceVCDescriptor) issuedAt() *time.Time {
-	return g.issuanceDate
-}
-
-func (g *GovernanceVCDescriptor) proofPurpose() string {
-	return "authentication"
-}
-
+// NewGovernanceVC creates a new governance verifiable credential descriptor.
+// DatasetDID and GovAddr are required. If ID is not provided, it will be generated.
+// If issuance date is not provided, it will be set to the current time at the generation.
 func NewGovernanceVC() *GovernanceVCDescriptor {
 	return &GovernanceVCDescriptor{}
 }
@@ -137,6 +146,14 @@ func (g *GovernanceVCDescriptor) prepare() error {
 	return nil
 }
 
+func (g *GovernanceVCDescriptor) issuedAt() *time.Time {
+	return g.issuanceDate
+}
+
+func (g *GovernanceVCDescriptor) proofPurpose() string {
+	return "authentication"
+}
+
 func (g *GovernanceVCDescriptor) generate() (*bytes.Buffer, error) {
 	err := g.prepare()
 	if err != nil {

diff --git a/credential/generate_test.go b/credential/generate_test.go
@@ -87,7 +87,7 @@ func TestGenerateGovernanceVC(t *testing.T) {
 				So(err, ShouldBeNil)
 
 				parser := credential.NewCredentialParser(docLoader)
-				generator := credential.NewGenerator(test.vc).
+				generator := credential.New(test.vc).
 					WithParser(parser)
 
 				Convey("When a governance VC is generated", func() {
@@ -135,17 +135,17 @@ func TestGenerator_Generate(t *testing.T) {
 	}{
 		{
 			name:      "without parser",
-			generator: credential.NewGenerator(credential.NewGovernanceVC().WithDatasetDID("datasetID").WithGovAddr("addr")),
+			generator: credential.New(credential.NewGovernanceVC().WithDatasetDID("datasetID").WithGovAddr("addr")),
 			wantErr:   errors.New("no parser provided"),
 		},
 		{
 			name:      "with descriptor error",
-			generator: credential.NewGenerator(credential.NewGovernanceVC().WithDatasetDID("datasetID")),
+			generator: credential.New(credential.NewGovernanceVC().WithDatasetDID("datasetID")),
 			wantErr:   credential.NewVCError(credential.ErrGenerate, errors.New("governance address is required")),
 		},
 		{
 			name: "without signature",
-			generator: credential.NewGenerator(credential.NewGovernanceVC().WithDatasetDID("datasetID").WithGovAddr("addr")).
+			generator: credential.New(credential.NewGovernanceVC().WithDatasetDID("datasetID").WithGovAddr("addr")).
 				WithParser(credential.NewCredentialParser(loader)),
 			wantErr: nil,
 			check: func(vc *verifiable.Credential) {
@@ -154,7 +154,7 @@ func TestGenerator_Generate(t *testing.T) {
 		},
 		{
 			name: "with signature",
-			generator: credential.NewGenerator(credential.NewGovernanceVC().WithDatasetDID("datasetID").WithGovAddr("addr")).
+			generator: credential.New(credential.NewGovernanceVC().WithDatasetDID("datasetID").WithGovAddr("addr")).
 				WithParser(credential.NewCredentialParser(loader)).
 				WithSignature(mockSigner, "did:example:123"),
 			wantErr: nil,