From 78d703f452325254440e6d451b6a0843b6b0dfe5 Mon Sep 17 00:00:00 2001
From: Felipe Noronha <felipenoris@gmail.com>
Date: Thu, 19 May 2016 10:02:30 -0300
Subject: [PATCH] docstring for @inferred

---
 base/test.jl        | 43 +++++++++++++++++++++++++++++++++++++++++++
 doc/stdlib/test.rst | 41 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+)

diff --git a/base/test.jl b/base/test.jl
index 79c60265471d3..55463983f6b4e 100644
--- a/base/test.jl
+++ b/base/test.jl
@@ -782,6 +782,49 @@ macro test_approx_eq(a, b)
     :(test_approx_eq($(esc(a)), $(esc(b)), $(string(a)), $(string(b))))
 end
 
+"""
+    @inferred f(x)
+
+Tests that the call expression `f(x)` returns a value of the same type
+inferred by the compiler. It's useful to check for type stability.
+
+`f(x)` can be any call expression, except a call for a generated function.
+Returns the result of `f(x)` if the types match, and an `Error` `Result` if
+it finds different types.
+
+```jldoctest
+julia> using Base.Test
+
+julia> f(a,b,c) = b > 1 ? 1 : 1.0
+f (generic function with 1 method)
+
+julia> typeof(f(1,2,3))
+Int64
+
+julia> @code_warntype f(1,2,3)
+Variables:
+  #self#::#f
+  a::Int64
+  b::Int64
+  c::Int64
+
+Body:
+  begin  # REPL[2], line 1:
+      unless (Base.slt_int)(1,b::Int64)::Bool goto 4
+      return 1
+      4:
+      return 1.0
+  end::Union{Float64,Int64}
+
+julia> @inferred f(1,2,3)
+ERROR: return type Int64 does not match inferred return type Union{Float64,Int64}
+ in error(::String) at ./error.jl:21
+ in eval(::Module, ::Any) at ./boot.jl:226
+
+julia> @inferred max(1,2)
+2
+```
+"""
 macro inferred(ex)
     ex.head == :call || error("@inferred requires a call expression")
     Base.remove_linenums!(quote
diff --git a/doc/stdlib/test.rst b/doc/stdlib/test.rst
index b2e17e2638295..29d7127493109 100644
--- a/doc/stdlib/test.rst
+++ b/doc/stdlib/test.rst
@@ -244,6 +244,47 @@ writing new tests.
 
    Test two floating point numbers ``a`` and ``b`` for equality taking in account a margin of tolerance given by ``tol``\ .
 
+.. function:: @inferred f(x)
+
+   .. Docstring generated from Julia source
+
+   Tests that the call expression ``f(x)`` returns a value of the same type inferred by the compiler. It's useful to check for type stability.
+
+   ``f(x)`` can be any call expression, except a call for a generated function. Returns the result of ``f(x)`` if the types match, and an ``Error`` ``Result`` if it finds different types.
+
+   .. doctest::
+
+       julia> using Base.Test
+
+       julia> f(a,b,c) = b > 1 ? 1 : 1.0
+       f (generic function with 1 method)
+
+       julia> typeof(f(1,2,3))
+       Int64
+
+       julia> @code_warntype f(1,2,3)
+       Variables:
+         #self#::#f
+         a::Int64
+         b::Int64
+         c::Int64
+
+       Body:
+         begin  # REPL[2], line 1:
+             unless (Base.slt_int)(1,b::Int64)::Bool goto 4
+             return 1
+             4:
+             return 1.0
+         end::Union{Float64,Int64}
+
+       julia> @inferred f(1,2,3)
+       ERROR: return type Int64 does not match inferred return type Union{Float64,Int64}
+        in error(::String) at ./error.jl:21
+        in eval(::Module, ::Any) at ./boot.jl:226
+
+       julia> @inferred max(1,2)
+       2
+
 Creating Custom ``AbstractTestSet`` Types
 -----------------------------------------