counter: upgrade documentation
STATUS.md was obsolete, and doc.go needed editing to reflect
current behavior of internal/counter.
Change-Id: Id23dbce2707898c1adf1dca1dc2cca9e6a732779
Reviewed-on: https://go-review.googlesource.com/c/telemetry/+/522240
Run-TryBot: Peter Weinberger <pjw@google.com>
Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>
Reviewed-by: Jamal Carvalho <jamal@golang.org>
TryBot-Result: Gopher Robot <gobot@golang.org>
diff --git a/counter/STATUS.md b/counter/STATUS.md
deleted file mode 100644
index f5b2373..0000000
--- a/counter/STATUS.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# Issues in the counter package
-
-## Generating reports and uploading
-
-The simplest story would be to generate and upload reports when the
-counter file is rotated, but uploads might fail, so that would not be
-enough. The proposed way is to start a separate command each time the
-counter package starts.
-
-The code could be in the counter package, or in a separate package, or
-in a separate command, for instance 'go telemetry upload'. The latter ties
-updates to the 'go' command release cycle, and separates the upload code from the
-counter package. Thus the code will be in the upload package.
-
-The init() function in upload.go handles this. It checks to see if the
-program was invoked with a single argument `__telemetry_upload__`, and if
-so, executes the code to generate reports and upload them. If not it spawns
-a copy of the current program with that argument.
-
-This commentary can be moved to the upload package when it is checked in.
-
-## TODOs
-
-There are a bunch of TODOs. Also there are many places in the upload code
-where log messages are written, but it's unclear how to recover from the
-errors. The log messages are written to files named `telemetry-<pid>.log`
-in `os.TempDir()`.
-
diff --git a/counter/countertest/countertest.go b/counter/countertest/countertest.go
index 6a30520..fe713e5 100644
--- a/counter/countertest/countertest.go
+++ b/counter/countertest/countertest.go
@@ -5,7 +5,7 @@
//go:build go1.21
// countertest provides testing utilities for counters.
-// Do not use this package except for testing.
+// This package cannot be used except for testing.
package countertest
import (
diff --git a/counter/doc.go b/counter/doc.go
index 641c4be..4160e84 100644
--- a/counter/doc.go
+++ b/counter/doc.go
@@ -13,16 +13,18 @@
// Counter files are stored in LocalDir(). Their content can be accessed
// by Parse().
//
-// Simple counters are very cheap. Stack counters are not collected if
-// go telemetry is disabled ("off").
+// Simple counters are very cheap. Stack counters are more
+// expensive, as they require parsing the stack.
// (Stack counters are implemented as a set of regular counters whose names
// are the concatenation of the name and the stack trace. There is an upper
// limit on the size of this name, about 4K bytes. If the name is too long
// the stack will be truncated and "truncated" appended.)
//
-// Counter files are turned into reports by the upload package.
-// This happens weekly, except for the first time a counter file is
-// created. Then it happens on a random day of the week more than 7 days
-// in the future. After that the counter files expire weekly on the same day of
+// When counter files expire they are turned into reports by the upload package.
+// The first time any counter file is created for a user, a random
+// day of the week is selected on which counter files will expire.
+// For the first week, that day is more than 7 days (but not more than
+// two weeks) in the future.
+// After that the counter files expire weekly on the same day of
// the week.
package counter
