docs: fix docs (#498)

Signed-off-by: Patrick Zheng <patrickzheng@microsoft.com>

Author: Two-Hearts

dir/path.go

@@ -59,6 +59,7 @@ const (
 	// PathSigningKeys is the signingkeys file relative path.
 	PathSigningKeys = "signingkeys.json"
 	// PathTrustPolicy is the OCI trust policy file relative path.
+	//
 	// Deprecated: PathTrustPolicy exists for historical compatibility and should not be used.
 	// To get OCI trust policy path, use PathOCITrustPolicy.
 	PathTrustPolicy = "trustpolicy.json"

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,14 +24,16 @@ import (
 	"github.com/notaryproject/notation-go/signer"
 )
 
-// ExampleSignBlob demonstrates how to use signer.BlobSign to sign arbitrary data.
+// ExampleSignBlob demonstrates how to use [notation.SignBlob] 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:
-	// https://github.com/notaryproject/notaryproject/blob/v1.0.0/specs/signature-specification.md#certificate-requirements
+	// following the Notary Project certificate requirements:
+	// https://github.com/notaryproject/specifications/tree/9c81dc773508dedc5a81c02c8d805de04f65050b/specs/signature-specification.md#certificate-requirements
 	exampleSigner, err := signer.NewGenericSigner(exampleCertTuple.PrivateKey, exampleCerts)
 	if err != nil {
 		panic(err) // Handle error
@@ -42,7 +44,7 @@ func Example_signBlob() {
 	exampleSignatureMediaType := jws.MediaTypeEnvelope
 	exampleContentMediaType := "video/mp4"
 
-	// exampleSignOptions is an example of notation.SignBlobOptions.
+	// exampleSignOptions is an example of [notation.SignBlobOptions].
 	exampleSignOptions := notation.SignBlobOptions{
 		SignerSignOptions: notation.SignerSignOptions{
 			SignatureMediaType: exampleSignatureMediaType,
@@ -52,7 +54,8 @@ func Example_signBlob() {
 		UserMetadata:     map[string]string{"buildId": "101"},
 	}
 
-	// exampleReader reads the data that needs to be signed. This data can be in a file or in memory.
+	// exampleReader reads the data that needs to be signed.
+	// This data can be in a file or in memory.
 	exampleReader := strings.NewReader("example blob")
 
 	// Upon successful signing, signature envelope and signerInfo are returned.

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/tree/9c81dc773508dedc5a81c02c8d805de04f65050b/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 [notation.VerifyBlob] 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 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
+	// https://github.com/notaryproject/specifications/tree/9c81dc773508dedc5a81c02c8d805de04f65050b/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.VerifyBlobOptions]
 	exampleVerifyOptions := notation.VerifyBlobOptions{
 		BlobVerifierVerifyOptions: notation.BlobVerifierVerifyOptions{
 			SignatureMediaType: exampleSignatureMediaType,
@@ -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/specifications/tree/9c81dc773508dedc5a81c02c8d805de04f65050b/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.Sign.
+// 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,18 +86,21 @@ 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
+
 	// ContentMediaType is the media-type of the blob being signed.
 	ContentMediaType string
+
 	// UserMetadata contains key-value pairs that are added to the signature
 	// payload
 	UserMetadata map[string]string
 }
 
 // BlobDescriptorGenerator creates descriptor using the digest Algorithm.
-// Below is the example of minimal descriptor, it must contain mediatype, digest and size of the artifact
+// Below is the example of minimal descriptor, it must contain mediatype,
+// digest and size of the artifact.
 //
 //	{
 //	   "mediaType": "application/octet-stream",
@@ -110,8 +113,8 @@ type BlobDescriptorGenerator func(digest.Algorithm) (ocispec.Descriptor, error)
 // The interface allows signing with local or remote keys,
 // and packing in various signature formats.
 type BlobSigner interface {
-	// SignBlob signs the descriptor returned by genDesc ,
-	// and returns the signature and SignerInfo
+	// SignBlob signs the descriptor returned by genDesc, and returns the
+	// signature and SignerInfo.
 	SignBlob(ctx context.Context, genDesc BlobDescriptorGenerator, opts SignerSignOptions) ([]byte, *signature.SignerInfo, error)
 }
 
@@ -122,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
 
@@ -200,7 +203,8 @@ func Sign(ctx context.Context, signer Signer, repo registry.Repository, signOpts
 	return targetDesc, nil
 }
 
-// SignBlob signs the arbitrary data and returns the signature
+// SignBlob signs the arbitrary data from blobReader and returns
+// the signature and SignerInfo.
 func SignBlob(ctx context.Context, signer BlobSigner, blobReader io.Reader, signBlobOpts SignBlobOptions) ([]byte, *signature.SignerInfo, error) {
 	// sanity checks
 	if err := validateSignArguments(signer, signBlobOpts.SignerSignOptions); err != nil {
@@ -325,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.
@@ -344,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
@@ -375,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)
@@ -386,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.
@@ -405,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
 
@@ -414,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