more discussion of x ≈ 0 in isapprox docs (#26029)

* more discussion of x ≈ 0 in isapprox docs

* tweak and typo

* clarification

* update in response to comments

* reduce example tolerance

Author: stevengj

base/floatfuncs.jl

@@ -214,6 +214,17 @@ approximately equal component-wise.
 The binary operator `≈` is equivalent to `isapprox` with the default arguments, and `x ≉ y`
 is equivalent to `!isapprox(x,y)`.
 
+Note that `x ≈ 0` (i.e., comparing to zero with the default tolerances) is
+equivalent to `x == 0` since the default `atol` is `0`.  In such cases, you should either
+supply an appropriate `atol` (or use `norm(x) ≤ atol`) or rearrange your code (e.g.
+use `x ≈ y` rather than `x - y ≈ 0`).   It is not possible to pick a nonzero `atol`
+automatically because it depends on the overall scaling (the "units") of your problem:
+for example, in `x - y ≈ 0`, `atol=1e-9` is an absurdly small tolerance if `x` is the
+[radius of the Earth](https://en.wikipedia.org/wiki/Earth_radius) in meters,
+but an absurdly large tolerance if `x` is the
+[radius of a Hydrogen atom](https://en.wikipedia.org/wiki/Bohr_radius) in meters.
+
+
 # Examples
 ```jldoctest
 julia> 0.1 ≈ (0.1 - 1e-10)
@@ -224,6 +235,12 @@ true
 
 julia> isapprox([10.0^9, 1.0], [10.0^9, 2.0])
 true
+
+julia> 1e-10 ≈ 0
+false
+
+julia> isapprox(1e-10, 0, atol=1e-8)
+true
 ```
 """
 function isapprox(x::Number, y::Number; atol::Real=0, rtol::Real=rtoldefault(x,y,atol), nans::Bool=false)