git » gofer » commit f1c75a7

nettrace: Improve documentation

author Alberto Bertogli
2022-11-13 11:13:49 UTC
committer Alberto Bertogli
2022-11-13 11:15:42 UTC
parent 5eef47a3aefab841ae8f211d9a9b7b1417e5e90c

nettrace: Improve documentation

nettrace/context.go +7 -1
nettrace/http.go +3 -0
nettrace/trace.go +5 -5

diff --git a/nettrace/context.go b/nettrace/context.go
index 665a98c..78663d5 100644
--- a/nettrace/context.go
+++ b/nettrace/context.go
@@ -4,17 +4,21 @@ import "context"
 
 type ctxKeyT string
 
-const ctxKey ctxKeyT = "blitiri.com.ar/go/srv/trace"
+const ctxKey ctxKeyT = "blitiri.com.ar/go/srv/nettrace"
 
+// NewContext returns a new context with the given trace attached.
 func NewContext(ctx context.Context, tr Trace) context.Context {
 	return context.WithValue(ctx, ctxKey, tr)
 }
 
+// FromContext returns the trace attached to the given context (if any).
 func FromContext(ctx context.Context) (Trace, bool) {
 	tr, ok := ctx.Value(ctxKey).(Trace)
 	return tr, ok
 }
 
+// FromContextOrNew returns the trace attached to the given context, or a new
+// trace if there is none.
 func FromContextOrNew(ctx context.Context, family, title string) (Trace, context.Context) {
 	tr, ok := FromContext(ctx)
 	if ok {
@@ -25,6 +29,8 @@ func FromContextOrNew(ctx context.Context, family, title string) (Trace, context
 	return tr, NewContext(ctx, tr)
 }
 
+// ChildFromContext returns a new trace that is a child of the one attached to
+// the context (if any).
 func ChildFromContext(ctx context.Context, family, title string) Trace {
 	parent, ok := FromContext(ctx)
 	if ok {
diff --git a/nettrace/http.go b/nettrace/http.go
index 2abae0e..2f51acc 100644
--- a/nettrace/http.go
+++ b/nettrace/http.go
@@ -30,10 +30,13 @@ func init() {
 		}).ParseFS(templatesFS, "templates/*"))
 }
 
+// RegisterHandler registers a the trace handler in the given ServeMux, on
+// `/debug/traces`.
 func RegisterHandler(mux *http.ServeMux) {
 	mux.HandleFunc("/debug/traces", RenderTraces)
 }
 
+// RenderTraces is an http.Handler that renders the tracing information.
 func RenderTraces(w http.ResponseWriter, req *http.Request) {
 	data := &struct {
 		Buckets   *[]time.Duration
diff --git a/nettrace/trace.go b/nettrace/trace.go
index 054566e..7013e48 100644
--- a/nettrace/trace.go
+++ b/nettrace/trace.go
@@ -1,5 +1,5 @@
-// Package trace implements tracing of requests. Traces are created by
-// trace.New, and can then be viewed over HTTP on /debug/traces.
+// Package nettrace implements tracing of requests. Traces are created by
+// nettrace.New, and can then be viewed over HTTP on /debug/traces.
 package nettrace
 
 import (
@@ -35,7 +35,7 @@ func (id id) Family() string {
 	return sp[0]
 }
 
-// A single trace.
+// Trace represents a single request trace.
 type Trace interface {
 	// NewChild creates a new trace, that is a child of this one.
 	NewChild(family, title string) Trace
@@ -149,6 +149,7 @@ func newTrace(family, title string) *trace {
 	return tr
 }
 
+// New creates a new trace with the given family and title.
 func New(family, title string) Trace {
 	return newTrace(family, title)
 }
@@ -255,9 +256,8 @@ func (tr *trace) Duration() time.Duration {
 
 	if end.IsZero() {
 		return time.Since(start)
-	} else {
-		return end.Sub(start)
 	}
+	return end.Sub(start)
 }
 
 // Events returns a copy of the trace events.