Document requirements for atsign-pure #25244
Description
There have been quite a number of mis-uses of @pure, and in some cases the resulting discussion about why reduces to "ask Jameson." Let's make it "read the docs" instead. Here's a possible head start:
"""
Base.@pure function f(args...)
#body
end
Marks function `f` as "pure," which means that the compiler should be allowed to replace `#body` with its resulting output. Marking a function as pure allows the operations to be performed at compile time rather than run time, potentially improving performance. In practice, it is only useful to mark functions taking only type or hard-coded constant inputs, since only in such cases does the compiler know the runtime values of the arguments.
To be a candidate for `@pure`, `f` must satisfy strict requirements:
- its output depends only on its arguments (it cannot depend on any additional state)
- it cannot have any side effects (no changes to any global variables, etc.)
- it cannot engage in I/O, even on an error path
Marking an impure function with `@pure` can lead to serious errors, including both incorrect results and runtime crashes.
"""