update docs

Signed-off-by: Patrick Zheng <[email protected]>

example_localSign_test.go

@@ -46,7 +46,7 @@ func Example_localSign() {
 	// exampleSigner is a notation.Signer given key and X509 certificate chain.
 	// Users should replace `exampleCertTuple.PrivateKey` with their own private
 	// key and replace `exampleCerts` with the corresponding full certificate
-	// chain, following the Notary certificate requirements:
+	// chain, following the Notary Project certificate requirements:
 	// https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements
 	exampleSigner, err := signer.NewGenericSigner(exampleCertTuple.PrivateKey, exampleCerts)
 	if err != nil {

example_localVerify_test.go

@@ -73,8 +73,8 @@ func Example_localVerify() {
 	}
 
 	// createTrustStore creates a trust store directory for demo purpose.
-	// Users could use the default trust store from Notary and add trusted
-	// certificates into it following the trust store spec:
+	// Users could use the default trust store from Notary Project and
+	// add trusted certificates into it following the trust store spec:
 	// https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/trust-store-trust-policy.md#trust-store
 	if err := createTrustStore(); err != nil {
 		panic(err) // Handle error
@@ -172,7 +172,7 @@ func createTrustStore() error {
 	// generate the `exampleSignatureEnvelopePem` above.)
 	// Users should replace `exampleX509Certificate` with their own trusted
 	// certificate and add to the trust store, following the
-	// Notary certificate requirements:
+	// Notary Project certificate requirements:
 	// https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements
 	exampleX509Certificate := `-----BEGIN CERTIFICATE-----
 MIIDQDCCAiigAwIBAgIBUTANBgkqhkiG9w0BAQsFADBOMQswCQYDVQQGEwJVUzEL

example_remoteSign_test.go

@@ -45,7 +45,7 @@ func Example_remoteSign() {
 	// exampleSigner is a notation.Signer given key and X509 certificate chain.
 	// Users should replace `exampleCertTuple.PrivateKey` with their own private
 	// key and replace `exampleCerts` with the corresponding full certificate
-	// chain, following the Notary certificate requirements:
+	// chain, following the Notary Project certificate requirements:
 	// https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements
 	exampleSigner, err := signer.NewGenericSigner(exampleCertTuple.PrivateKey, exampleCerts)
 	if err != nil {

example_remoteVerify_test.go

@@ -101,7 +101,7 @@ func generateTrustStore() error {
 	// an example of a valid X509 self-signed certificate for demo purpose ONLY.
 	// Users should replace `exampleX509Certificate` with their own trusted
 	// certificate and add to the trust store, following the
-	// Notary certificate requirements:
+	// Notary Project certificate requirements:
 	// https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements
 	exampleX509Certificate := `-----BEGIN CERTIFICATE-----
 MIIDQDCCAiigAwIBAgIBUTANBgkqhkiG9w0BAQsFADBOMQswCQYDVQQGEwJVUzEL

example_signBlob_test.go

@@ -24,13 +24,15 @@ import (
 	"github.com/notaryproject/notation-go/signer"
 )
 
-// ExampleSignBlob demonstrates how to use signer.BlobSign to sign arbitrary data.
+// ExampleSignBlob demonstrates how to use [signer.BlobSign] to sign arbitrary
+// data.
 func Example_signBlob() {
-	//exampleSigner implements notation.Signer and notation.BlobSigner. Given key and X509 certificate chain,
-	// it provides method to sign OCI artifacts or blobs.
+	// exampleSigner implements [notation.Signer] and [notation.BlobSigner].
+	// Given key and X509 certificate chain, it provides method to sign OCI
+	// artifacts or blobs.
 	// Users should replace `exampleCertTuple.PrivateKey` with their own private
 	// key and replace `exampleCerts` with the corresponding certificate chain,
-	//following the Notary certificate requirements:
+	//following the Notary Project certificate requirements:
 	// https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements
 	exampleSigner, err := signer.NewGenericSigner(exampleCertTuple.PrivateKey, exampleCerts)
 	if err != nil {

example_signWithTimestmap_test.go

@@ -45,7 +45,7 @@ func Example_signWithTimestamp() {
 	// exampleSigner is a notation.Signer given key and X509 certificate chain.
 	// Users should replace `exampleCertTuple.PrivateKey` with their own private
 	// key and replace `exampleCerts` with the corresponding full certificate
-	// chain, following the Notary certificate requirements:
+	// chain, following the Notary Project certificate requirements:
 	// https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements
 	exampleSigner, err := signer.NewGenericSigner(exampleCertTuple.PrivateKey, exampleCerts)
 	if err != nil {

example_verifyBlob_test.go

@@ -27,9 +27,9 @@ import (
 	"github.com/notaryproject/notation-go/verifier/truststore"
 )
 
-// examplePolicyDocument is an example of a valid trust policy document.
-// trust policy document should follow this spec:
-// https://github.com/notaryproject/notaryproject/blob/v1.1.0/specs/trust-store-trust-policy.md#trust-policy
+// exampleBlobPolicyDocument is an example of a valid blob trust policy document.
+// blob trust policy document should follow this spec:
+// https://github.com/notaryproject/specifications/blob/main/specs/trust-store-trust-policy.md#blob-trust-policy
 var exampleBlobPolicyDocument = trustpolicy.BlobDocument{
 	Version: "1.0",
 	TrustPolicies: []trustpolicy.BlobTrustPolicy{
@@ -42,8 +42,8 @@ var exampleBlobPolicyDocument = trustpolicy.BlobDocument{
 	},
 }
 
-// ExampleVerifyBlob demonstrates how to use verifier.Verify to verify a
-// signature of the blob.
+// ExampleVerifyBlob demonstrates how to use [verifier.Verify] to verify a
+// signature of an arbitrary blob.
 func Example_verifyBlob() {
 	// Both COSE ("application/cose") and JWS ("application/jose+json")
 	// signature mediaTypes are supported.
@@ -53,23 +53,24 @@ func Example_verifyBlob() {
 	exampleSignatureEnvelope := getSignatureEnvelope()
 
 	// createTrustStoreForBlobVerify creates a trust store directory for demo purpose.
-	// Users could use the default trust store from Notary and add trusted
+	// Users could use the default trust store from Notation and add trusted
 	// certificates into it following the trust store spec:
-	// https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/trust-store-trust-policy.md#trust-store
+	// https://github.com/notaryproject/notaryproject/blob/v1.1.0/specs/trust-store-trust-policy.md#trust-store
 	if err := createTrustStoreForBlobVerify(); err != nil {
 		panic(err) // Handle error
 	}
 
-	// exampleVerifier implements notation.Verify and notation.VerifyBlob.
+	// exampleVerifier implements [notation.Verify] and [notation.VerifyBlob].
 	exampleVerifier, err := verifier.NewVerifier(nil, &exampleBlobPolicyDocument, truststore.NewX509TrustStore(dir.ConfigFS()), nil)
 	if err != nil {
 		panic(err) // Handle error
 	}
 
-	// exampleReader reads the data that needs to be verified. This data can be in a file or in memory.
+	// exampleReader reads the data that needs to be verified.
+	// This data can be in a file or in memory.
 	exampleReader := strings.NewReader("example blob")
 
-	// exampleVerifyOptions is an example of notation.VerifierVerifyOptions
+	// exampleVerifyOptions is an example of [notation.VerifierVerifyOptions]
 	exampleVerifyOptions := notation.VerifyBlobOptions{
 		BlobVerifierVerifyOptions: notation.BlobVerifierVerifyOptions{
 			SignatureMediaType: exampleSignatureMediaType,
@@ -91,7 +92,7 @@ func Example_verifyBlob() {
 
 	// Note, upon successful verification, payload.TargetArtifact from the
 	// signature envelope matches exactly with our exampleTargetDescriptor.
-	// (This check has been done for the user inside verifier.Verify.)
+	// (This check has been done for the user inside [verifier.Verify].)
 	fmt.Println("payload Content:", string(outcome.EnvelopeContent.Payload.Content))
 
 	// Output:
@@ -110,8 +111,8 @@ func createTrustStoreForBlobVerify() error {
 	// generate the `exampleSignatureEnvelopePem` above.)
 	// Users should replace `exampleX509Certificate` with their own trusted
 	// certificate and add to the trust store, following the
-	// Notary certificate requirements:
-	// https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements
+	// Notary Project certificate requirements:
+	// https://github.com/notaryproject/notaryproject/blob/v1.1.0/specs/signature-specification.md#certificate-requirements
 	exampleX509Certificate := `-----BEGIN CERTIFICATE-----
 MIIEbDCCAtSgAwIBAgIBUzANBgkqhkiG9w0BAQsFADBkMQswCQYDVQQGEwJVUzEL
 MAkGA1UECBMCV0ExEDAOBgNVBAcTB1NlYXR0bGUxDzANBgNVBAoTBk5vdGFyeTEl

example_verifyWithTimestamp_test.go

@@ -115,7 +115,7 @@ func generateTrustStoreWithTimestamp() error {
 	// an example of a valid X509 self-signed certificate for demo purpose ONLY.
 	// Users should replace `exampleX509Certificate` with their own trusted
 	// certificate and add to the trust store, following the
-	// Notary certificate requirements:
+	// Notary Project certificate requirements:
 	// https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements
 	exampleX509Certificate := `-----BEGIN CERTIFICATE-----
 MIIDQDCCAiigAwIBAgIBUTANBgkqhkiG9w0BAQsFADBOMQswCQYDVQQGEwJVUzEL
@@ -149,7 +149,7 @@ GLAfj/jSf9OH9VLTPHOS8/N0Ka4=
 	// an example of a valid TSA root certificate for demo purpose ONLY.
 	// Users should replace `exampleTSARootCertificate` with their own trusted
 	// TSA root certificate and add to the trust store, following the
-	// Notary certificate requirements:
+	// Notary Project certificate requirements:
 	// https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements
 	exampleTSARootCertificate := `-----BEGIN CERTIFICATE-----
 		MIIFkDCCA3igAwIBAgIQBZsbV56OITLiOQe9p3d1XDANBgkqhkiG9w0BAQwFADBi

notation.go

@@ -12,7 +12,7 @@
 // limitations under the License.
 
 // Package notation provides signer and verifier for notation Sign
-// and Verification.
+// and Verification. It supports both OCI artifact and arbitrary blob.
 package notation
 
 import (
@@ -48,7 +48,7 @@ var errDoneVerification = errors.New("done verification")
 
 var reservedAnnotationPrefixes = [...]string{"io.cncf.notary"}
 
-// SignerSignOptions contains parameters for Signer and BlobSigner.
+// SignerSignOptions contains parameters for [Signer] and [BlobSigner].
 type SignerSignOptions struct {
 	// SignatureMediaType is the envelope type of the signature.
 	// Currently, both `application/jose+json` and `application/cose` are
@@ -86,7 +86,7 @@ type Signer interface {
 	Sign(ctx context.Context, desc ocispec.Descriptor, opts SignerSignOptions) ([]byte, *signature.SignerInfo, error)
 }
 
-// SignBlobOptions contains parameters for notation.SignBlob.
+// SignBlobOptions contains parameters for [notation.SignBlob].
 type SignBlobOptions struct {
 	SignerSignOptions
 
@@ -125,7 +125,7 @@ type signerAnnotation interface {
 	PluginAnnotations() map[string]string
 }
 
-// SignOptions contains parameters for notation.Sign.
+// SignOptions contains parameters for [notation.Sign].
 type SignOptions struct {
 	SignerSignOptions
 
@@ -329,7 +329,8 @@ func (outcome *VerificationOutcome) UserMetadata() (map[string]string, error) {
 	return payload.TargetArtifact.Annotations, nil
 }
 
-// VerifierVerifyOptions contains parameters for Verifier.Verify used for verifying OCI artifact.
+// VerifierVerifyOptions contains parameters for [Verifier.Verify] used for
+// verifying OCI artifact.
 type VerifierVerifyOptions struct {
 	// ArtifactReference is the reference of the artifact that is being
 	// verified against to. It must be a full reference.
@@ -348,17 +349,17 @@ type VerifierVerifyOptions struct {
 	UserMetadata map[string]string
 }
 
-// Verifier is a interface for verifying an OCI artifact.
+// Verifier is a generic interface for verifying an OCI artifact.
 type Verifier interface {
 	// Verify verifies the `signature` associated with the target OCI artifact
-	//with manifest descriptor `desc`, and returns the outcome upon
+	// with manifest descriptor `desc`, and returns the outcome upon
 	// successful verification.
 	// If nil signature is present and the verification level is not 'skip',
 	// an error will be returned.
 	Verify(ctx context.Context, desc ocispec.Descriptor, signature []byte, opts VerifierVerifyOptions) (*VerificationOutcome, error)
 }
 
-// BlobVerifierVerifyOptions contains parameters for BlobVerifier.Verify.
+// BlobVerifierVerifyOptions contains parameters for [BlobVerifier.Verify].
 type BlobVerifierVerifyOptions struct {
 	// SignatureMediaType is the envelope type of the signature.
 	// Currently only `application/jose+json` and `application/cose` are
@@ -379,7 +380,7 @@ type BlobVerifierVerifyOptions struct {
 
 // BlobVerifier is a generic interface for verifying a blob.
 type BlobVerifier interface {
-	// VerifyBlob verifies the `signature` against the target artifact using the
+	// VerifyBlob verifies the `signature` against the target blob using the
 	// descriptor returned by descGenFunc parameter and
 	// returns the outcome upon  successful verification.
 	VerifyBlob(ctx context.Context, descGenFunc BlobDescriptorGenerator, signature []byte, opts BlobVerifierVerifyOptions) (*VerificationOutcome, error)
@@ -390,7 +391,7 @@ type verifySkipper interface {
 	SkipVerify(ctx context.Context, opts VerifierVerifyOptions) (bool, *trustpolicy.VerificationLevel, error)
 }
 
-// VerifyOptions contains parameters for notation.Verify.
+// VerifyOptions contains parameters for [notation.Verify].
 type VerifyOptions struct {
 	// ArtifactReference is the reference of the artifact that is being
 	// verified against to.
@@ -409,7 +410,7 @@ type VerifyOptions struct {
 	UserMetadata map[string]string
 }
 
-// VerifyBlobOptions contains parameters for notation.VerifyBlob.
+// VerifyBlobOptions contains parameters for [notation.VerifyBlob].
 type VerifyBlobOptions struct {
 	BlobVerifierVerifyOptions
 
@@ -418,9 +419,9 @@ type VerifyBlobOptions struct {
 }
 
 // VerifyBlob performs signature verification for a blob using notation supported
-// verification types (like integrity, authenticity, etc.) and return the
-// successful signature verification outcome. The blob is read using blobReader and
-// upon successful verification, it returns the descriptor of the blob.
+// verification types (like integrity, authenticity, etc.) and returns the
+// successful signature verification outcome. The blob is read using blobReader,
+// and upon successful verification, it returns the descriptor of the blob.
 // For more details on signature verification, see
 // https://github.com/notaryproject/notaryproject/blob/main/specs/trust-store-trust-policy.md#signature-verification
 func VerifyBlob(ctx context.Context, blobVerifier BlobVerifier, blobReader io.Reader, signature []byte, verifyBlobOpts VerifyBlobOptions) (ocispec.Descriptor, *VerificationOutcome, error) {

plugin/manager.go

@@ -35,7 +35,7 @@ type Manager interface {
 	List(ctx context.Context) ([]string, error)
 }
 
-// CLIManager implements Manager
+// CLIManager implements [Manager]
 type CLIManager struct {
 	pluginFS dir.SysFS
 }

plugin/plugin.go

@@ -40,26 +40,30 @@ const maxPluginOutputSize = 64 * 1024 * 1024 // 64 MiB
 var executor commander = &execCommander{} // for unit test
 
 // GenericPlugin is the base requirement to be a plugin.
+//
 // Deprecated: GenericPlugin exists for historical compatibility and should not be used.
 // To access GenericPlugin, use the notation-plugin-framework-go's plugin.GenericPlugin type.
 type GenericPlugin = plugin.GenericPlugin
 
 // SignPlugin defines the required methods to be a SignPlugin.
+//
 // Deprecated: SignPlugin exists for historical compatibility and should not be used.
 // To access SignPlugin, use the notation-plugin-framework-go's plugin.SignPlugin type.
 type SignPlugin = plugin.SignPlugin
 
 // VerifyPlugin defines the required method to be a VerifyPlugin.
+//
 // Deprecated: VerifyPlugin exists for historical compatibility and should not be used.
 // To access VerifyPlugin, use the notation-plugin-framework-go's plugin.VerifyPlugin type.
 type VerifyPlugin = plugin.VerifyPlugin
 
 // Plugin defines required methods to be a Plugin.
+//
 // Deprecated: Plugin exists for historical compatibility and should not be used.
 // To access Plugin, use the notation-plugin-framework-go's plugin.Plugin type.
 type Plugin = plugin.Plugin
 
-// CLIPlugin implements Plugin interface to CLI plugins.
+// CLIPlugin implements [Plugin] interface to CLI plugins.
 type CLIPlugin struct {
 	name string
 	path string

registry/repository.go

@@ -48,17 +48,17 @@ var (
 	notationEmptyConfigData = ocispec.DescriptorEmptyJSON.Data
 )
 
-// RepositoryOptions provides user options when creating a Repository
+// RepositoryOptions provides user options when creating a [Repository]
 // it is kept for future extensibility
 type RepositoryOptions struct{}
 
-// repositoryClient implements Repository
+// repositoryClient implements [Repository]
 type repositoryClient struct {
 	oras.GraphTarget
 	RepositoryOptions
 }
 
-// NewRepository returns a new Repository.
+// NewRepository returns a new [Repository].
 // Known implementations of oras.GraphTarget:
 // - [remote.Repository](https://pkg.go.dev/oras.land/oras-go/v2/registry/remote#Repository)
 // - [oci.Store](https://pkg.go.dev/oras.land/oras-go/v2/content/oci#Store)
@@ -68,7 +68,7 @@ func NewRepository(target oras.GraphTarget) Repository {
 	}
 }
 
-// NewRepositoryWithOptions returns a new Repository with user specified
+// NewRepositoryWithOptions returns a new [Repository] with user specified
 // options.
 func NewRepositoryWithOptions(target oras.GraphTarget, opts RepositoryOptions) Repository {
 	return &repositoryClient{
@@ -77,7 +77,7 @@ func NewRepositoryWithOptions(target oras.GraphTarget, opts RepositoryOptions) R
 	}
 }
 
-// NewOCIRepository returns a new Repository with oci.Store as
+// NewOCIRepository returns a new [Repository] with oci.Store as
 // its oras.GraphTarget. `path` denotes directory path to the target OCI layout.
 func NewOCIRepository(path string, opts RepositoryOptions) (Repository, error) {
 	fileInfo, err := os.Stat(path)

signer/plugin.go

@@ -36,7 +36,7 @@ import (
 
 // PluginSigner signs artifacts and generates signatures.
 //
-// It implements notation.Signer and notation.BlobSigner.
+// It implements [notation.Signer] and [notation.BlobSigner].
 type PluginSigner struct {
 	plugin              plugin.SignPlugin
 	keyID               string
@@ -50,17 +50,17 @@ var algorithms = map[crypto.Hash]digest.Algorithm{
 	crypto.SHA512: digest.SHA512,
 }
 
-// NewFromPlugin creates a PluginSigner that signs artifacts and generates
+// NewFromPlugin creates a [PluginSigner] that signs artifacts and generates
 // signatures by delegating the one or more operations to the named plugin,
 // as defined in https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#signing-interfaces.
 //
-// Deprecated: NewFromPlugin function exists for historical compatibility and should not be used.
-// To create PluginSigner, use NewPluginSigner() function.
+// Deprecated: NewFromPlugin function exists for historical compatibility and
+// should not be used. To create [PluginSigner], use NewPluginSigner() function.
 func NewFromPlugin(plugin plugin.SignPlugin, keyID string, pluginConfig map[string]string) (notation.Signer, error) {
 	return NewPluginSigner(plugin, keyID, pluginConfig)
 }
 
-// NewPluginSigner creates a PluginSigner that signs artifacts and generates
+// NewPluginSigner creates a [PluginSigner] that signs artifacts and generates
 // signatures by delegating the one or more operations to the named plugin,
 // as defined in https://github.com/notaryproject/notaryproject/blob/main/specs/plugin-extensibility.md#signing-interfaces.
 func NewPluginSigner(plugin plugin.SignPlugin, keyID string, pluginConfig map[string]string) (*PluginSigner, error) {