Added docstring to @fastmath macro. (#22359)

* Added docstring to @fastmath macro.

Adds docstring to @fastmath macro that explains a bit about what it does, and includes examples how to use it.

* Updated per yuyichao's comments

Added link to  [LLVM Fast-Math flags](http://llvm.org/docs/LangRef.html#fast-math-flags)

* Indented docstring first line

* added @fastmath to math.md @doc

* added link to performance annotations, removed bulleted details

* fixed intra-doc link && wrap 92.

* added "be careful" warning as well.

* s/Executes/Execute/g

Author: NHDaly

base/fastmath.jl

@@ -5,7 +5,8 @@
 # This module provides versions of math functions that may violate
 # strict IEEE semantics.
 
-# This allows the following transformations:
+# This allows the following transformations. For more information see
+# http://llvm.org/docs/LangRef.html#fast-math-flags:
 # nnan: No NaNs - Allow optimizations to assume the arguments and
 #       result are not NaN. Such optimizations are required to retain
 #       defined behavior over NaNs, but the value of the result is
@@ -124,6 +125,27 @@ function make_fastmath(symb::Symbol)
 end
 make_fastmath(expr) = expr
 
+"""
+    @fastmath expr
+
+Execute a transformed version of the expression, which calls functions that
+may violate strict IEEE semantics. This allows the fastest possible operation,
+but results are undefined -- be careful when doing this, as it may change numerical
+results.
+
+This sets the [LLVM Fast-Math flags](http://llvm.org/docs/LangRef.html#fast-math-flags),
+and corresponds to the `-ffast-math` option in clang. See [the notes on performance
+annotations](@ref man-performance-annotations) for more details.
+
+# Examples
+```jldoctest
+julia> @fastmath 1+2
+3
+
+julia> @fastmath(sin(3))
+0.1411200080598672
+```
+"""
 macro fastmath(expr)
     make_fastmath(esc(expr))
 end

doc/src/manual/performance-tips.md

@@ -1082,7 +1082,7 @@ These are some minor points that might help in tight inner loops.
   * Use [`div(x,y)`](@ref) for truncating division of integers instead of [`trunc(x/y)`](@ref), [`fld(x,y)`](@ref)
     instead of [`floor(x/y)`](@ref), and [`cld(x,y)`](@ref) instead of [`ceil(x/y)`](@ref).
 
-## Performance Annotations
+## [Performance Annotations](@id man-performance-annotations)
 
 Sometimes you can enable better optimization by promising certain program properties.
 

doc/src/stdlib/math.md

@@ -181,6 +181,7 @@ Base.Math.lbeta
 Base.ndigits
 Base.widemul
 Base.Math.@evalpoly
+Base.FastMath.@fastmath
 ```
 
 ## Statistics