cli/command/formatter: NewStats: update GoDoc and add TODO

Update the GoDoc to better align with the actual implementation. The
"idOrName" is used for fuzzy-matching the container, which can result
in multiple stats for the same container:

    docker ps --format 'table {{.ID}}\t{{.Names}}'
    CONTAINER ID   NAMES
    b49e6c21d12e   quizzical_maxwell

    docker stats --no-stream quizzical_maxwell b49e6c21d12e b49e6
    CONTAINER ID   NAME                CPU %     MEM USAGE / LIMIT     MEM %     NET I/O           BLOCK I/O        PIDS
    b49e6c21d12e   quizzical_maxwell   0.10%     140.8MiB / 7.653GiB   1.80%     3.11MB / 13.4kB   115MB / 1.12MB   28
    b49e6c21d12e   quizzical_maxwell   0.10%     140.8MiB / 7.653GiB   1.80%     3.11MB / 13.4kB   115MB / 1.12MB   28
    b49e6c21d12e   quizzical_maxwell   0.10%     140.8MiB / 7.653GiB   1.80%     3.11MB / 13.4kB   115MB / 1.12MB   28

We should resolve the canonical ID once, then use that as reference
to prevent duplicates. Various  parts in the code compare Container
against "ID" only (not considering "name" or "ID-prefix").

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

Author: thaJeztah

cli/command/container/formatter_stats.go

@@ -112,9 +112,14 @@ func NewStatsFormat(source, osType string) formatter.Format {
 	return formatter.Format(source)
 }
 
-// NewStats returns a new Stats entity and sets in it the given name
-func NewStats(container string) *Stats {
-	return &Stats{StatsEntry: StatsEntry{Container: container}}
+// NewStats returns a new Stats entity using the given ID, ID-prefix, or
+// name to resolve the container.
+func NewStats(idOrName string) *Stats {
+	// FIXME(thaJeztah): "idOrName" is used for fuzzy-matching the container, which can result in multiple stats for the same container.
+	// We should resolve the canonical ID once, then use that as reference
+	// to prevent duplicates. Various parts in the code compare Container
+	// against "ID" only (not considering "name" or "ID-prefix").
+	return &Stats{StatsEntry: StatsEntry{Container: idOrName}}
 }
 
 // statsFormatWrite renders the context for a list of containers statistics