Document the relationship between groups, versions, kinds, and resources. Link

pkg/api/meta/interfaces.go

@@ -142,8 +142,17 @@ type RESTMapping struct {
 // RESTMapper allows clients to map resources to kind, and map kind and version
 // to interfaces for manipulating those objects. It is primarily intended for
 // consumers of Kubernetes compatible REST APIs as defined in docs/api-conventions.md.
+//
+// The Kubernetes API provides versioned resources and object kinds which are scoped
+// to API groups. In other words, kinds and resources should not be assumed to be
+// unique across groups.
+//
+// TODO(caesarxuchao): Add proper multi-group support so that kinds & resources are
+// scoped to groups. See http://issues.k8s.io/12413 and http://issues.k8s.io/10009.
 type RESTMapper interface {
 	VersionAndKindForResource(resource string) (defaultVersion, kind string, err error)
+	// TODO(caesarxuchao): Remove GroupForResource when multi-group support is in (since
+	// group will be part of the version).
 	GroupForResource(resource string) (string, error)
 	RESTMapping(kind string, versions ...string) (*RESTMapping, error)
 	AliasesForResource(resource string) ([]string, bool)