doc: add docstrings for Base.front and Base.tail (JuliaLang#31132)

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))
 

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

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)

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
 

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