Doc base macros (#27949)

base/expr.jl

@@ -199,6 +199,20 @@ macro noinline(ex)
  esc(isa(ex, Expr) ? pushmeta!(ex, :noinline) : ex)
 end
 
+"""
+ @pure ex
+ @pure(ex)
+
+`@pure` gives the compiler a hint for the definition of a pure function,
+helping for type inference.
+
+A pure function can only depend on immutable information.
+This also means a `@pure` function cannot use any global mutable state, including
+generic functions. Calls to generic functions depend on method tables which are
+mutable global state.
+Use with caution, incorrect `@pure` annotation of a function may introduce
+hard to identify bugs. Double check for calls to generic functions.
+"""
 macro pure(ex)
  esc(isa(ex, Expr) ? pushmeta!(ex, :pure) : ex)
 end
@@ -347,6 +361,35 @@ macro generated()
  return Expr(:generated)
 end
 
+"""
+ @generated f
+ @generated(f)
+`@generated` is used to annotate a function which will be generated.
+In the body of the generated function, only types of arguments can be read
+(not the values). The function returns a quoted expression evaluated when the
+function is called. The `@generated` macro should not be used on functions mutating
+the global scope or depending on mutable elements.
+
+See [Metaprogramming](@ref) for further details.
+
+## Example:
+```julia
+julia> @generated function bar(x)
+ if x <: Integer
+ return :(x ^ 2)
+ else
+ return :(x)
+ end
+ end
+bar (generic function with 1 method)
+
+julia> bar(4)
+16
+
+julia> bar("baz")
+"baz"
+```
+"""
 macro generated(f)
  if isa(f, Expr) && (f.head === :function || is_short_function_def(f))
  body = f.args[2]

base/int.jl

@@ -553,14 +553,36 @@ floor(::Type{T}, x::Integer) where {T<:Integer} = convert(T, x)
 
 ## integer construction ##
 
+"""
+ @int128_str str
+ @int128_str(str)
+
+`@int128_str` parses a string into a Int128
+Throws an `ArgumentError` if the string is not a valid integer
+"""
 macro int128_str(s)
  return parse(Int128, s)
 end
 
+"""
+ @uint128_str str
+ @uint128_str(str)
+
+`@uint128_str` parses a string into a UInt128
+Throws an `ArgumentError` if the string is not a valid integer
+"""
 macro uint128_str(s)
  return parse(UInt128, s)
 end
 
+"""
+ @big_str str
+ @big_str(str)
+
+`@big_str` parses a string into a BigInt
+Throws an `ArgumentError` if the string is not a valid integer
+Removes all underscores `_` from the string
+"""
 macro big_str(s)
  if '_' in s
  # remove _ in s[2:end-1]

base/irrationals.jl

@@ -136,6 +136,13 @@ end
 
 round(x::Irrational, r::RoundingMode) = round(float(x), r)
 
+"""
+ @irrational sym val def
+ @irrational(sym, val, def)
+
+Define a new `Irrational` value, `sym`, with pre-computed `Float64` value `val`,
+and arbitrary-precision definition in terms of `BigFloat`s given be the expression `def`.
+"""
 macro irrational(sym, val, def)
  esym = esc(sym)
  qsym = esc(Expr(:quote, sym))

base/math.jl

@@ -89,7 +89,10 @@ function clamp!(x::AbstractArray, lo, hi)
  x
 end
 
-# evaluate p[1] + x * (p[2] + x * (....)), i.e. a polynomial via Horner's rule
+"""
+ @horner(x, p...)
+ Evaluate p[1] + x * (p[2] + x * (....)), i.e. a polynomial via Horner's rule
+"""
 macro horner(x, p...)
  ex = esc(p[end])
  for i = length(p)-1:-1:1

doc/src/base/base.md

@@ -220,6 +220,8 @@ Base.@goto
 Base.@label
 Base.@simd
 Base.@polly
+Base.@generated
+Base.@pure
 ```
 
 ## Missing Values

doc/src/base/numbers.md

@@ -109,6 +109,8 @@ Base.trailing_zeros
 Base.trailing_ones
 Base.isodd
 Base.iseven
+Base.@int128_str
+Base.@uint128_str
 ```
 
 ## BigFloats
@@ -124,4 +126,5 @@ Base.MPFR.BigFloat(x, prec::Int)
 BigFloat(x::Union{Integer, AbstractFloat, String}, rounding::RoundingMode)
 Base.MPFR.BigFloat(x, prec::Int, rounding::RoundingMode)
 Base.MPFR.BigFloat(x::String)
+Base.@big_str
 ```