From da406e36227eb650c4df4ab5a83dcedc00645ef2 Mon Sep 17 00:00:00 2001
From: Sung Yoon Whang <sungyoon@uber.com>
Date: Fri, 28 Oct 2022 12:22:04 -0700
Subject: [PATCH] Chore: Fix deprecation docs and links (#1193)

Some of the doc comments on deprecated APIs weren't formatted correctly
and wasn't showing up as deprecated on pkg.go.dev.

This fixes those incorrectly formatted docs. Also added links to point
to the new APIs that deprecated them.
---
 options.go         |  3 ++-
 sugar_test.go      |  2 +-
 zapcore/entry.go   |  3 ++-
 zapgrpc/zapgrpc.go | 10 +++++++---
 4 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/options.go b/options.go
index 1511166c0..c4f3bca3d 100644
--- a/options.go
+++ b/options.go
@@ -133,7 +133,8 @@ func IncreaseLevel(lvl zapcore.LevelEnabler) Option {
 }
 
 // OnFatal sets the action to take on fatal logs.
-// Deprecated: Use WithFatalHook instead.
+//
+// Deprecated: Use [WithFatalHook] instead.
 func OnFatal(action zapcore.CheckWriteAction) Option {
 	return WithFatalHook(action)
 }
diff --git a/sugar_test.go b/sugar_test.go
index 602c4326a..9e914ecf8 100644
--- a/sugar_test.go
+++ b/sugar_test.go
@@ -220,7 +220,7 @@ func TestSugarStructuredLogging(t *testing.T) {
 		extra          = []interface{}{err, "baz", false}
 		expectedFields = []Field{String("foo", "bar"), Error(err), Bool("baz", false)}
 	)
-	
+
 	for _, tt := range tests {
 		withSugar(t, DebugLevel, nil, func(logger *SugaredLogger, logs *observer.ObservedLogs) {
 			logger.With(context...).Debugw(tt.msg, extra...)
diff --git a/zapcore/entry.go b/zapcore/entry.go
index ea0431eb3..9d326e95e 100644
--- a/zapcore/entry.go
+++ b/zapcore/entry.go
@@ -281,7 +281,8 @@ func (ce *CheckedEntry) AddCore(ent Entry, core Core) *CheckedEntry {
 // Should sets this CheckedEntry's CheckWriteAction, which controls whether a
 // Core will panic or fatal after writing this log entry. Like AddCore, it's
 // safe to call on nil CheckedEntry references.
-// Deprecated: Use After(ent Entry, after CheckWriteHook) instead.
+//
+// Deprecated: Use [CheckedEntry.After] instead.
 func (ce *CheckedEntry) Should(ent Entry, should CheckWriteAction) *CheckedEntry {
 	return ce.After(ent, should)
 }
diff --git a/zapgrpc/zapgrpc.go b/zapgrpc/zapgrpc.go
index 356e12741..71ca30b51 100644
--- a/zapgrpc/zapgrpc.go
+++ b/zapgrpc/zapgrpc.go
@@ -61,6 +61,7 @@ func (f optionFunc) apply(log *Logger) {
 // WithDebug configures a Logger to print at zap's DebugLevel instead of
 // InfoLevel.
 // It only affects the Printf, Println and Print methods, which are only used in the gRPC v1 grpclog.Logger API.
+//
 // Deprecated: use grpclog.SetLoggerV2() for v2 API.
 func WithDebug() Option {
 	return optionFunc(func(logger *Logger) {
@@ -146,19 +147,22 @@ type Logger struct {
 }
 
 // Print implements grpclog.Logger.
-// Deprecated: use Info().
+//
+// Deprecated: use [Logger.Info].
 func (l *Logger) Print(args ...interface{}) {
 	l.print.Print(args...)
 }
 
 // Printf implements grpclog.Logger.
-// Deprecated: use Infof().
+//
+// Deprecated: use [Logger.Infof].
 func (l *Logger) Printf(format string, args ...interface{}) {
 	l.print.Printf(format, args...)
 }
 
 // Println implements grpclog.Logger.
-// Deprecated: use Info().
+//
+// Deprecated: use [Logger.Info].
 func (l *Logger) Println(args ...interface{}) {
 	l.print.Println(args...)
 }