Update GetManifest documentation for empty MIME type

https://github.com/containers/image/pull/139 has changed the semantics
to always expect a value from an ImageSource; that’s not really great
when the source has no idea, but we don’t have optionals in Golang to
distinguish between a nonsensical "" and unavailable, so this is at
least making the documentation consistent.

Hopefully ImageSources which call manifest.GuessMIMEType in GetManifest
will not proliferate…

Signed-off-by: Miloslav Trmač <mitr@redhat.com>

directory/directory_src.go

@@ -30,7 +30,8 @@ func (s *dirImageSource) Reference() types.ImageReference {
 func (s *dirImageSource) Close() {
 }
 
-// it's up to the caller to determine the MIME type of the returned manifest's bytes
+// GetManifest returns the image's manifest along with its MIME type (which may be empty when it can't be determined but the manifest is available).
+// It may use a remote (= slow) service.
 func (s *dirImageSource) GetManifest() ([]byte, string, error) {
 	m, err := ioutil.ReadFile(s.ref.manifestPath())
 	if err != nil {

docker/daemon/daemon_src.go

@@ -290,7 +290,7 @@ func (s *daemonImageSource) prepareLayerData(tarManifest *manifestItem, parsedCo
 	return knownLayers, nil
 }
 
-// GetManifest returns the image's manifest along with its MIME type. The empty string is returned if the MIME type is unknown.
+// GetManifest returns the image's manifest along with its MIME type (which may be empty when it can't be determined but the manifest is available).
 // It may use a remote (= slow) service.
 func (s *daemonImageSource) GetManifest() ([]byte, string, error) {
 	if s.generatedManifest == nil {

docker/docker_image_src.go

@@ -67,6 +67,8 @@ func simplifyContentType(contentType string) string {
 	return mimeType
 }
 
+// GetManifest returns the image's manifest along with its MIME type (which may be empty when it can't be determined but the manifest is available).
+// It may use a remote (= slow) service.
 func (s *dockerImageSource) GetManifest() ([]byte, string, error) {
 	err := s.ensureManifestIsLoaded()
 	if err != nil {

image/manifest.go

@@ -89,11 +89,11 @@ func manifestInstanceFromBlob(src types.ImageSource, manblob []byte, mt string)
 	case manifest.DockerV2ListMediaType:
 		return manifestSchema2FromManifestList(src, manblob)
 	default:
-		// if it's not a recognized manifest media type we'll try the last time
+		// If it's not a recognized manifest media type, or we have failed determining the type, we'll try one last time
 		// to deserialize using v2s1 as per https://github.com/docker/distribution/blob/master/manifests.go#L108
 		// and https://github.com/docker/distribution/blob/master/manifest/schema1/manifest.go#L50
 		//
-		// Crane registries can return "text/plain" also.
+		// Crane registries can also return "text/plain", or pretty much anything else depending on a file extension “recognized” in the tag.
 		// This makes no real sense, but it happens
 		// because requests for manifests are
 		// redirected to a content distribution

image/sourced.go

@@ -71,7 +71,7 @@ func FromUnparsedImage(unparsed *UnparsedImage) (types.Image, error) {
 	}, nil
 }
 
-// Manifest overrides the UnparsedImage.Manifest to use the fields which we have already fetched, after guessing and overrides.
+// Manifest overrides the UnparsedImage.Manifest to always use the fields which we have already fetched.
 func (i *sourcedImage) Manifest() ([]byte, string, error) {
 	return i.manifestBlob, i.manifestMIMEType, nil
 }

openshift/openshift.go

@@ -203,6 +203,8 @@ func (s *openshiftImageSource) GetTargetManifest(digest string) ([]byte, string,
 	return s.docker.GetTargetManifest(digest)
 }
 
+// GetManifest returns the image's manifest along with its MIME type (which may be empty when it can't be determined but the manifest is available).
+// It may use a remote (= slow) service.
 func (s *openshiftImageSource) GetManifest() ([]byte, string, error) {
 	if err := s.ensureImageIsResolved(); err != nil {
 		return nil, "", err

types/types.go

@@ -108,7 +108,7 @@ type ImageSource interface {
 	Reference() ImageReference
 	// Close removes resources associated with an initialized ImageSource, if any.
 	Close()
-	// GetManifest returns the image's manifest along with its MIME type. The empty string is returned if the MIME type is unknown.
+	// GetManifest returns the image's manifest along with its MIME type (which may be empty when it can't be determined but the manifest is available).
 	// It may use a remote (= slow) service.
 	GetManifest() ([]byte, string, error)
 	// GetTargetManifest returns an image's manifest given a digest. This is mainly used to retrieve a single image's manifest