docs: warn against @big_str not obeying rounding mode or precision (#…

…50800)

One of the big pitfalls when using `BigFloat`.

base/int.jl

@@ -754,6 +754,15 @@ julia> big"_"
 ERROR: ArgumentError: invalid number format _ for BigInt or BigFloat
 [...]
 ```
+
+!!! warning
+ Using `@big_str` for constructing [`BigFloat`](@ref) values may not result
+ in the behavior that might be naively expected: as a macro, `@big_str`
+ obeys the global precision ([`setprecision`](@ref)) and rounding mode
+ ([`setrounding`](@ref)) settings as they are at *load time*. Thus, a
+ function like `() -> precision(big"0.3")` returns a constant whose value
+ depends on the value of the precision at the point when the function is
+ defined, **not** at the precision at the time when the function is called.
 """
 macro big_str(s)
  message = "invalid number format $s for BigInt or BigFloat"

doc/src/manual/integers-and-floating-point-numbers.md

@@ -653,6 +653,13 @@ julia> setprecision(40) do
 1.1000000000004
 ```
 
+!!! warning
+ The relation between [`setprecision`](@ref) or [`setrounding`](@ref) and
+ [`@big_str`](@ref), the macro used for `big` string literals (such as
+ `big"0.3"`), might not be intuitive, as a consequence of the fact that
+ `@big_str` is a macro. See the [`@big_str`](@ref) documentation for
+ details.
+
 ## [Numeric Literal Coefficients](@id man-numeric-literal-coefficients)
 
 To make common numeric formulae and expressions clearer, Julia allows variables to be immediately