From 95fcde9dda4261ebd9dd2eb694b46fc74e472ef6 Mon Sep 17 00:00:00 2001
From: Jan Weidner <jw3126@gmail.com>
Date: Thu, 14 Mar 2019 09:49:31 +0100
Subject: [PATCH] doc: add docstrings for Base.front and Base.tail (#31132)

---
 base/essentials.jl          | 16 ++++++++++++++++
 base/tuple.jl               | 16 +++++++++++++++-
 doc/src/base/collections.md |  2 ++
 test/namedtuple.jl          |  2 +-
 test/tuple.jl               |  1 +
 5 files changed, 35 insertions(+), 2 deletions(-)

diff --git a/base/essentials.jl b/base/essentials.jl
index 6912976373e50..6a7f1eb999473 100644
--- a/base/essentials.jl
+++ b/base/essentials.jl
@@ -183,7 +183,23 @@ macro eval(mod, ex)
 end
 
 argtail(x, rest...) = rest
+
+"""
+    tail(x::Tuple)::Tuple
+
+Return a `Tuple` consisting of all but the first component of `x`.
+
+# Examples
+```jldoctest
+julia> Base.tail((1,2,3))
+(2, 3)
+
+julia> Base.tail(())
+ERROR: ArgumentError: Cannot call tail on an empty tuple.
+```
+"""
 tail(x::Tuple) = argtail(x...)
+tail(::Tuple{}) = throw(ArgumentError("Cannot call tail on an empty tuple."))
 
 tuple_type_head(T::Type) = (@_pure_meta; fieldtype(T::Type{<:Tuple}, 1))
 
diff --git a/base/tuple.jl b/base/tuple.jl
index 9f45fec88c1b1..7e8c6804bc496 100644
--- a/base/tuple.jl
+++ b/base/tuple.jl
@@ -107,11 +107,25 @@ safe_tail(t::Tuple{}) = ()
 
 # front (the converse of tail: it skips the last entry)
 
+"""
+    front(x::Tuple)::Tuple
+
+Return a `Tuple` consisting of all but the last component of `x`.
+
+# Examples
+```jldoctest
+julia> Base.front((1,2,3))
+(1, 2)
+
+julia> Base.front(())
+ERROR: ArgumentError: Cannot call front on an empty tuple.
+```
+"""
 function front(t::Tuple)
     @_inline_meta
     _front(t...)
 end
-_front() = throw(ArgumentError("Cannot call front on an empty tuple"))
+_front() = throw(ArgumentError("Cannot call front on an empty tuple."))
 _front(v) = ()
 function _front(v, t...)
     @_inline_meta
diff --git a/doc/src/base/collections.md b/doc/src/base/collections.md
index 2e5ad94307e84..d947786689056 100644
--- a/doc/src/base/collections.md
+++ b/doc/src/base/collections.md
@@ -128,6 +128,8 @@ Base.mapfoldl(::Any, ::Any, ::Any)
 Base.mapfoldr(::Any, ::Any, ::Any)
 Base.first
 Base.last
+Base.front
+Base.tail
 Base.step
 Base.collect(::Any)
 Base.collect(::Type, ::Any)
diff --git a/test/namedtuple.jl b/test/namedtuple.jl
index bd4bf2eef6c64..369ed5fdbd76b 100644
--- a/test/namedtuple.jl
+++ b/test/namedtuple.jl
@@ -118,7 +118,7 @@ end
 @test get(()->0, (a=1,), :b) == 0
 @test Base.tail((a = 1, b = 2.0, c = 'x')) ≡ (b = 2.0, c = 'x')
 @test Base.tail((a = 1, )) ≡ NamedTuple()
-@test_throws MethodError Base.tail(NamedTuple())
+@test_throws ArgumentError Base.tail(NamedTuple())
 
 # syntax errors
 
diff --git a/test/tuple.jl b/test/tuple.jl
index 9b56ccff20fbe..eded9639a75c3 100644
--- a/test/tuple.jl
+++ b/test/tuple.jl
@@ -97,6 +97,7 @@ end
     @test length((1,2)) === 2
 
     @test_throws ArgumentError Base.front(())
+    @test_throws ArgumentError Base.tail(())
     @test_throws ArgumentError first(())
 
     @test lastindex(()) === 0