proposal: more updates to code coverage revamp design document

More specific details on user-callable APIs for writing coverage data.

Updates golang/go#51430.

Change-Id: I9ebe2f20ee7fc6b37aadef7fd16dc97ee5b67da8
Reviewed-on: https://go-review.googlesource.com/c/proposal/+/409994
Reviewed-by: Than McIntosh <thanm@google.com>

1 files changed, 43 insertions, 15 deletions

diff --git a/design/51430-revamp-code-coverage.md b/design/51430-revamp-code-coverage.md
index db9509f..7d167f1 100644
--- a/design/51430-revamp-code-coverage.md
+++ b/design/51430-revamp-code-coverage.md
@@ -213,38 +213,66 @@ Austin for this idea).
 
 To handle server programs (which in many cases run forever and may not call
 exit), APIs will be provided for writing out a coverage profile under user
-control, e.g. something along the lines of
+control. The first API variants will support writing coverage data to a specific
+directory path:
 
 ```Go
-  import "<someOfficialPath>/cover"
+  import "runtime/coverage"
 
   var *coverageoutdir flag.String(...)
 
   func server() {
     ...
     if *coverageoutdir != "" {
-        f, err := cover.OpenCoverageOutputFile(...)
-        if err != nil {
-            log.Fatal("...")
-	   }
+      // Meta-data is already available on program startup; write it now.
+      // NB: we're assuming here that the specified dir already exists
+      if err := coverage.EmitMetaDataToDir(*coverageoutdir); err != nil {
+        log.Fatalf("writing coverage meta-data: %v")
+      }
     }
     for {
       ...
-      if <received signal to emit coverage data> {
-        err := f.Emit()
-        if err != nil {
-            log.Fatalf("error %v emitting ...", err)
+      if *coverageoutdir != "" && <received signal to emit coverage data> {
+        if err := coverage.EmitCounterDataToDir(*coverageoutdir); err != nil {
+          log.Fatalf("writing coverage counter-data: %v")
         }
       }
     }
+  }
+```
+
+The second API variants will support writing coverage meta-data and counter data to a user-specified io.Writer (where the io.Writer is presumably backed by a pipe or network connection of some sort):
+
+```Go
+  import "runtime/coverage"
+
+  var *codecoverageflag flag.Bool(...)
 
+  func server() {
+    ...
+    var w io.Writer
+    if *codecoverageflag {
+      // Meta-data is already available on program startup; write it now.
+      w = <obtain destination io.Writer somehow>
+      if err := coverage.EmitMetaDataToWriter(w); err != nil {
+        log.Fatalf("writing coverage meta-data: %v")
+      }
+    }
+    for {
+      ...
+      if *codecoverageflag && <received signal to emit coverage data> {
+        if err := coverage.EmitCounterDataToWriter(w); err != nil {
+          log.Fatalf("writing coverage counter-data: %v")
+        }
+      }
+    }
+  }
 ```
- 
-In addition to OpenCoverageOutputFile() and Emit() as above, an Emit() function
-will be provided that accepts an io.Writer (to allow coverage profiles to be
-written to a network connection or pipe, in case writing to a file is not
-possible).
 
+These APIs will return an error if invoked from within an application not built
+with the "-cover" flag.
+
+ 
 ### Coverage and modules
 
 Most modern Go programs make extensive use of dependent third-party packages;