document that inv(x) is not just for matrices (#22610)

* document that inv(x) is not just for matrices

* rm blank line

* caveat about roundoff errors

base/number.jl

@@ -133,9 +133,35 @@ copysign(x::Real, y::Real) = ifelse(signbit(x)!=signbit(y), -x, +x)
 conj(x::Real) = x
 transpose(x::Number) = x
 ctranspose(x::Number) = conj(x)
-inv(x::Number) = one(x)/x
 angle(z::Real) = atan2(zero(z), z)
 
+"""
+    inv(x)
+
+Return the multiplicative inverse of `x`, such that `x*inv(x)` or `inv(x)*x`
+yields [`one(x)`](@ref) (the multiplicative identity) up to roundoff errors.
+
+If `x` is a number, this is essentially the same as `one(x)/x`, but for
+some types `inv(x)` may be slightly more efficient.
+
+# Examples
+```jldoctest
+julia> inv(2)
+0.5
+
+julia> inv(1 + 2im)
+0.2 - 0.4im
+
+julia> inv(1 + 2im) * (1 + 2im)
+1.0 + 0.0im
+
+julia> inv(2//3)
+3//2
+```
+"""
+inv(x::Number) = one(x)/x
+
+
 """
     widemul(x, y)
 

doc/src/stdlib/linalg.md

@@ -85,7 +85,7 @@ Base.LinAlg.trace
 Base.LinAlg.det
 Base.LinAlg.logdet
 Base.LinAlg.logabsdet
-Base.inv
+Base.inv(::AbstractMatrix)
 Base.LinAlg.pinv
 Base.LinAlg.nullspace
 Base.repmat

doc/src/stdlib/math.md

@@ -12,6 +12,7 @@ Base.:\(::Any, ::Any)
 Base.:^(::Number, ::Number)
 Base.fma
 Base.muladd
+Base.inv(::Number)
 Base.div
 Base.fld
 Base.cld