From fc6e0a5799842ccb505521e57e718dcc003a6674 Mon Sep 17 00:00:00 2001 From: Patrick Ohly Date: Mon, 28 Oct 2024 09:01:51 +0100 Subject: [PATCH] apiserver: avoid TODO in public docs As pointed out in https://github.com/kubernetes/kubernetes/pull/126387#discussion_r1811009830, having TODOs in the Go doc comments makes them visible to downstream developers. Using "Contextual logging: " as special prefix serves the same purpose (search/replace as explained in https://github.com/kubernetes/kubernetes/issues/126379) and makes the doc comment human-readable. Keeping that information visible is useful because developers might care, even if logcheck doesn't warn them yet. --- staging/src/k8s.io/apimachinery/pkg/util/runtime/runtime.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/staging/src/k8s.io/apimachinery/pkg/util/runtime/runtime.go b/staging/src/k8s.io/apimachinery/pkg/util/runtime/runtime.go index 4fe0c5eb250..df374949dd5 100644 --- a/staging/src/k8s.io/apimachinery/pkg/util/runtime/runtime.go +++ b/staging/src/k8s.io/apimachinery/pkg/util/runtime/runtime.go @@ -45,7 +45,7 @@ var PanicHandlers = []func(context.Context, interface{}){logPanic} // // E.g., you can provide one or more additional handlers for something like shutting down go routines gracefully. // -// TODO(pohly): logcheck:context // HandleCrashWithContext should be used instead of HandleCrash in code which supports contextual logging. +// Contextual logging: HandleCrashWithContext should be used instead of HandleCrash in code which supports contextual logging. func HandleCrash(additionalHandlers ...func(interface{})) { if r := recover(); r != nil { additionalHandlersWithContext := make([]func(context.Context, interface{}), len(additionalHandlers)) @@ -146,7 +146,7 @@ type ErrorHandler func(ctx context.Context, err error, msg string, keysAndValues // is preferable to logging the error - the default behavior is to log but the // errors may be sent to a remote server for analysis. // -// TODO(pohly): logcheck:context // HandleErrorWithContext should be used instead of HandleError in code which supports contextual logging. +// Contextual logging: HandleErrorWithContext should be used instead of HandleError in code which supports contextual logging. func HandleError(err error) { // this is sometimes called with a nil error. We probably shouldn't fail and should do nothing instead if err == nil {