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.

Author: sywhang

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)
 }

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...)

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)
 }

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...)
 }