From 54abb6b8c7658592bb7e24c16ffbd9e7ab049ec4 Mon Sep 17 00:00:00 2001
From: Jack Koenig <koenig@sifive.com>
Date: Tue, 25 Mar 2025 09:28:11 -0700
Subject: [PATCH] Fix UInt unary negation ScalaDoc

Deprecate invalid unary operator unary_-%.
---
 core/src/main/scala-2/chisel3/BitsIntf.scala | 8 ++++++--
 core/src/main/scala-3/chisel3/BitsIntf.scala | 6 ++++--
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/core/src/main/scala-2/chisel3/BitsIntf.scala b/core/src/main/scala-2/chisel3/BitsIntf.scala
index 4821bb05e24..e8f3d4f9a93 100644
--- a/core/src/main/scala-2/chisel3/BitsIntf.scala
+++ b/core/src/main/scala-2/chisel3/BitsIntf.scala
@@ -277,7 +277,7 @@ private[chisel3] trait BitsIntf extends ToBoolable { self: Bits =>
 private[chisel3] trait UIntIntf { self: UInt =>
 
   // TODO: refactor to share documentation with Num or add independent scaladoc
-  /** Unary negation (expanding width)
+  /** Unary negation (constant width)
     *
     * @return a $coll equal to zero minus this $coll
     * $constantWidth
@@ -287,16 +287,18 @@ private[chisel3] trait UIntIntf { self: UInt =>
 
   /** Unary negation (constant width)
     *
-    * @return a $coll equal to zero minus this $coll shifted right by one.
+    * @return a $coll equal to zero minus this $coll
     * $constantWidth
     * @group Arithmetic
     */
+  @deprecated("Use unary_- which has the same behavior", "Chisel 6.8.0")
   final def unary_-% : UInt = macro SourceInfoTransform.noArg
 
   /** @group SourceInfoTransformMacro */
   def do_unary_-(implicit sourceInfo: SourceInfo): UInt = _impl_unary_-
 
   /** @group SourceInfoTransformMacro */
+  @deprecated("Use unary_- which has the same behavior", "Chisel 6.8.0")
   def do_unary_-%(implicit sourceInfo: SourceInfo): UInt = _impl_unary_-%
 
   override def do_+(that: UInt)(implicit sourceInfo: SourceInfo): UInt = _impl_+(that)
@@ -553,12 +555,14 @@ private[chisel3] trait SIntIntf { self: SInt =>
     * $constantWidth
     * @group Arithmetic
     */
+  @deprecated("Use unary_- which has the same behavior", "Chisel 6.8.0")
   final def unary_-% : SInt = macro SourceInfoTransform.noArg
 
   /** @group SourceInfoTransformMacro */
   def do_unary_-(implicit sourceInfo: SourceInfo): SInt = _impl_unary_-
 
   /** @group SourceInfoTransformMacro */
+  @deprecated("Use unary_- which has the same behavior", "Chisel 6.8.0")
   def do_unary_-%(implicit sourceInfo: SourceInfo): SInt = _impl_unary_-%
 
   /** add (default - no growth) operator */
diff --git a/core/src/main/scala-3/chisel3/BitsIntf.scala b/core/src/main/scala-3/chisel3/BitsIntf.scala
index 8e37fcbd165..4f911871555 100644
--- a/core/src/main/scala-3/chisel3/BitsIntf.scala
+++ b/core/src/main/scala-3/chisel3/BitsIntf.scala
@@ -190,7 +190,7 @@ private[chisel3] trait BitsIntf extends ToBoolable { self: Bits =>
 private[chisel3] trait UIntIntf { self: UInt =>
 
   // TODO: refactor to share documentation with Num or add independent scaladoc
-  /** Unary negation (expanding width)
+  /** Unary negation (constant width)
     *
     * @return a $coll equal to zero minus this $coll
     * $constantWidth
@@ -204,6 +204,7 @@ private[chisel3] trait UIntIntf { self: UInt =>
     * $constantWidth
     * @group Arithmetic
     */
+  @deprecated("Use unary_- which has the same behavior", "Chisel 6.8.0")
   def unary_-%(using SourceInfo): UInt = _impl_unary_-%
 
   override def +(that: UInt): UInt = _impl_+(that)
@@ -398,10 +399,11 @@ private[chisel3] trait SIntIntf { self: SInt =>
 
   /** Unary negation (constant width)
     *
-    * @return a hardware $coll equal to zero minus `this` shifted right by one
+    * @return a hardware $coll equal to zero minus `this` $coll
     * $constantWidth
     * @group Arithmetic
     */
+  @deprecated("Use unary_- which has the same behavior", "Chisel 6.8.0")
   def unary_-%(using SourceInfo): SInt = _impl_unary_-%
 
   /** add (default - no growth) operator */