resolved comments

Signed-off-by: Xiaoxuan Wang <[email protected]>

example_pack_test.go

@@ -35,7 +35,8 @@ func ExamplePackManifest_imageV11() {
 	opts := oras.PackManifestOptions{
 		ManifestAnnotations: map[string]string{
 			// this timestamp will be automatically generated if not specified
-			// use a fixed value here in order to test the output
+			// use a fixed value here in order to test the output and make the
+			// pack reproducible.
 			ocispec.AnnotationCreated: "2000-01-01T00:00:00Z",
 		},
 	}
@@ -71,7 +72,8 @@ func ExamplePackManifest_imageV10() {
 	opts := oras.PackManifestOptions{
 		ManifestAnnotations: map[string]string{
 			// this timestamp will be automatically generated if not specified
-			// use a fixed value here in order to test the output
+			// use a fixed value here in order to test the output and make the
+			// pack reproducible.
 			ocispec.AnnotationCreated: "2000-01-01T00:00:00Z",
 		},
 	}

pack.go

@@ -48,8 +48,8 @@ const (
 
 var (
 	// ErrInvalidDateTimeFormat is returned by [Pack] and [PackManifest] when
-	// AnnotationArtifactCreated or AnnotationCreated is provided, but its value
-	// is not in RFC 3339 format.
+	// "org.opencontainers.artifact.created" or "org.opencontainers.image.created"
+	// is provided, but its value is not in RFC 3339 format.
 	// Reference: https://www.rfc-editor.org/rfc/rfc3339#section-5.6
 	ErrInvalidDateTimeFormat = errors.New("invalid date and time format")
 
@@ -93,9 +93,9 @@ type PackManifestOptions struct {
 	// Layers is the layers of the manifest.
 	Layers []ocispec.Descriptor
 
-	// ManifestAnnotations is the annotation map of the manifest. Set
-	// "org.opencontainers.image.created" with a value to make PackManifest
-	// reproducible.
+	// ManifestAnnotations is the annotation map of the manifest. In order to
+	// make PackManifest reproducible, set the key ocispec.AnnotationCreated to
+	// a fixed value. The value must conform to RFC 3339.
 	ManifestAnnotations map[string]string
 
 	// ConfigDescriptor is a pointer to the descriptor of the config blob.
@@ -129,9 +129,9 @@ var mediaTypeRegexp = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9!#$&-^_.+]{0,126
 // artifactType and opts.ConfigDescriptor.MediaType MUST comply with RFC 6838.
 //
 // Each time when PackManifest is called, it generates a new time stamp in the
-// manifest annotations with the key "org.opencontainers.image.created". To make
-// PackManifest reproducible, set "org.opencontainers.image.created" with a value
-// in opts.ManifestAnnotations.
+// manifest annotations with the key ocispec.AnnotationCreated. To make
+// PackManifest reproducible, set the key ocispec.AnnotationCreated to a fixed value
+// in opts.ManifestAnnotations. The value MUST conform to RFC 3339.
 //
 // If succeeded, returns a descriptor of the packed manifest.
 func PackManifest(ctx context.Context, pusher content.Pusher, packManifestVersion PackManifestVersion, artifactType string, opts PackManifestOptions) (ocispec.Descriptor, error) {