gone_in(9): bring the manual page up to date

Fixes:	01addd846c

share/man/man9/gone_in.9

@@ -23,7 +23,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd August 16, 2021
+.Dd June 24, 2025
 .Dt GONE_IN 9
 .Os
 .Sh NAME
@@ -33,14 +33,15 @@
 .Sh SYNOPSIS
 .In sys/systm.h
 .Ft void
-.Fn gone_in "int major" "const char *msg"
+.Fn gone_in "int major" "const char *msg" "..."
 .Ft void
-.Fn gone_in_dev "device_t dev" "int major" "const char *msg"
+.Fn gone_in_dev "device_t dev" "int major" "const char *msg" "..."
 .Sh DESCRIPTION
 The
-.Fn gone_in
-functions are used to provide a notice that the kernel is using a driver or
-some other functionality that is deprecated, and will be removed in a future
+.Nm gone_in
+functions are used to provide a notice that the kernel is actively using a
+driver or some other functionality that is deprecated, and is planned for
+removal in a future
 .Fx
 release.
 The notice is sent to the kernel
@@ -51,30 +52,29 @@ The
 argument specifies the major version of the
 .Fx
 release that will remove the deprecated functionality.
+The notice shall be printed only once, thus
+.Nm
+functions are safe to use in often executed code paths.
+.Pp
+.Nm gone_in_dev
+will prepend driver name before the notice.
 .Pp
 In releases before
 .Fa major
-the deprecation notice states
+the provided notice will be appended with
 .Do
-Deprecated code (to be removed in FreeBSD
-.Fa major Ns ):
-.Fa msg
-.Dc .
-In releases equal to and after
-.Fa major
-the notice states
-.Do
-Obsolete code will be removed soon:
-.Fa msg
+To be removed in FreeBSD
+.Fa major Ns
 .Dc .
 .Sh EXAMPLES
 .Bd -literal -offset indent
 void
-sample_init(void)
+example_api(foo_t *args)
 {
-	/* Initialization code omitted. */
+	gone_in(16, "Warning! %s[%u] uses obsolete API. ",
+	    curthread->td_proc->p_comm, curthread->td_proc->p_pid);
 
-	gone_in(14, "Giant-locked filesystem");
+	/* API implementation omitted. */
 }
 
 int
@@ -82,7 +82,7 @@ example_driver_attach(struct example_driver_softc *sc)
 {
 	/* Attach code omitted. */
 
-        gone_in_dev(sc->dev, 14, "Giant-locked driver");
+        gone_in_dev(sc->dev, 16, "driver is deprecated");
 }
 .Ed
 .Sh HISTORY