Make Base.depwarn() public (#55212)

There's a few reasons for making it public:
- It's already mentioned in the manual (#54211).
- It's the easiest way to deprecate a function that shouldn't be used
anymore at all.
- It's already widely used in the ecosystem:
https://juliahub.com/ui/Search?type=code&q=Base.depwarn(

I also moved the `@deprecate` docs into a new `Managing deprecations`
section because I felt it should go together with `Base.depwarn()`.
Might be worth backporting to 1.11?

Author: JamesWrigley

base/deprecated.jl

@@ -119,9 +119,7 @@ export __has_internal_change
 # and of exporting the function.
 #
 # For more complex cases, move the body of the deprecated method in this file,
-# and call depwarn() directly from inside it. The symbol depwarn() expects is
-# the name of the function, which is used to ensure that the deprecation warning
-# is only printed the first time for each call place.
+# and call depwarn() directly from inside it.
 
 """
     @deprecate old new [export_old=true]
@@ -131,6 +129,8 @@ with the specified signature in the process.
 
 To prevent `old` from being exported, set `export_old` to `false`.
 
+See also [`Base.depwarn()`](@ref).
+
 !!! compat "Julia 1.5"
     As of Julia 1.5, functions defined by `@deprecate` do not print warning when `julia`
     is run without the `--depwarn=yes` flag set, as the default value of `--depwarn` option
@@ -227,6 +227,26 @@ macro deprecate(old, new, export_old=true)
     end
 end
 
+"""
+    Base.depwarn(msg::String, funcsym::Symbol; force=false)
+
+Print `msg` as a deprecation warning. The symbol `funcsym` should be the name
+of the calling function, which is used to ensure that the deprecation warning is
+only printed the first time for each call place. Set `force=true` to force the
+warning to always be shown, even if Julia was started with `--depwarn=no` (the
+default).
+
+See also [`@deprecate`](@ref).
+
+# Examples
+```julia
+function deprecated_func()
+    Base.depwarn("Don't use `deprecated_func()`!", :deprecated_func)
+
+    1 + 1
+end
+```
+"""
 @nospecializeinfer function depwarn(msg, funcsym; force::Bool=false)
     @nospecialize
     # N.B. With this use of `@invokelatest`, we're preventing the addition of backedges from

base/public.jl

@@ -112,4 +112,5 @@ public
 # misc
     notnothing,
     runtests,
-    text_colors
+    text_colors,
+    depwarn

doc/src/base/base.md

@@ -311,7 +311,12 @@ Base.@simd
 Base.@polly
 Base.@generated
 Base.@assume_effects
+```
+
+## Managing deprecations
+```@docs
 Base.@deprecate
+Base.depwarn
 ```
 
 ## Missing Values