From c85de3b044e942a0231a671b7c762a897a951ac9 Mon Sep 17 00:00:00 2001
From: Christian Kurz <c.kurz@tu-bs.de>
Date: Wed, 20 Sep 2017 08:43:15 +0200
Subject: [PATCH 1/6] Add `See also: ` to pop!, shift! and splice!

#23788
---
 base/array.jl | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/base/array.jl b/base/array.jl
index 64189afa33219..92c5f012b43c5 100644
--- a/base/array.jl
+++ b/base/array.jl
@@ -1080,6 +1080,8 @@ end
 Remove an item in `collection` and return it. If `collection` is an
 ordered container, the last item is returned.
 
+See also: shift!, splice!
+
 # Examples
 ```jldoctest
 julia> A=[1, 2, 3]
@@ -1147,6 +1149,8 @@ end
 
 Remove the first `item` from `collection`.
 
+See also: pop!, splice!
+
 # Examples
 ```jldoctest
 julia> A = [1, 2, 3, 4, 5, 6]
@@ -1316,6 +1320,8 @@ Subsequent items are shifted left to fill the resulting gap.
 If specified, replacement values from an ordered
 collection will be spliced in place of the removed item.
 
+See also: pop!, shift!
+
 # Examples
 ```jldoctest splice!
 julia> A = [6, 5, 4, 3, 2, 1]; splice!(A, 5)

From 9d8a240c5cd2e8fe591ba03c5a7fce84b8daa74a Mon Sep 17 00:00:00 2001
From: Christian Kurz <c.kurz@tu-bs.de>
Date: Wed, 20 Sep 2017 09:21:51 +0200
Subject: [PATCH 2/6] added @ref syntax

---
 base/array.jl | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/base/array.jl b/base/array.jl
index 92c5f012b43c5..c503177a3634b 100644
--- a/base/array.jl
+++ b/base/array.jl
@@ -1080,7 +1080,7 @@ end
 Remove an item in `collection` and return it. If `collection` is an
 ordered container, the last item is returned.
 
-See also: shift!, splice!
+See also: [`shift!`](@ref), [`splice!`](@ref)
 
 # Examples
 ```jldoctest
@@ -1149,7 +1149,7 @@ end
 
 Remove the first `item` from `collection`.
 
-See also: pop!, splice!
+See also: [`pop!`](@ref), [`splice!`](@ref)
 
 # Examples
 ```jldoctest
@@ -1320,7 +1320,7 @@ Subsequent items are shifted left to fill the resulting gap.
 If specified, replacement values from an ordered
 collection will be spliced in place of the removed item.
 
-See also: pop!, shift!
+See also: [`pop!`](@ref), [`shift!`](@ref)
 
 # Examples
 ```jldoctest splice!

From 590e74a71f7719bda9a9e1cab5fa0b8d3da0b99c Mon Sep 17 00:00:00 2001
From: Christian Kurz <c.kurz@tu-bs.de>
Date: Thu, 21 Sep 2017 10:25:10 +0200
Subject: [PATCH 3/6] Added antonyms, updated docs of append!

`See also`-Lists now contain up to two related functions and antonym at the end

Docs of `append!` were not in line with `prepend!`.
---
 base/array.jl | 38 +++++++++++++++++++++++++++++++-------
 1 file changed, 31 insertions(+), 7 deletions(-)

diff --git a/base/array.jl b/base/array.jl
index c503177a3634b..6f554099ccec4 100644
--- a/base/array.jl
+++ b/base/array.jl
@@ -883,6 +883,9 @@ _deleteat!(a::Vector, i::Integer, delta::Integer) =
 
 Insert one or more `items` at the end of `collection`.
 
+**See also:**
+[`unshift!`](@ref), [`insert!`](@ref), [`pop!`](@ref)
+
 # Examples
 ```jldoctest
 julia> push!([1, 2, 3], 4, 5, 6)
@@ -916,9 +919,12 @@ function push!(a::Array{Any,1}, @nospecialize item)
 end
 
 """
-    append!(collection, collection2) -> collection.
+    append!(a::Vector, items) -> collection.
+
+Add the elements of `items` to the end of `a`.
 
-Add the elements of `collection2` to the end of `collection`.
+**See also:**
+[`prepend!`](@ref), [`insert!`](@ref)
 
 # Examples
 ```jldoctest
@@ -974,6 +980,9 @@ end
 
 Insert the elements of `items` to the beginning of `a`.
 
+**See also:**
+[`append!`](@ref), [`insert!`](@ref)
+
 # Examples
 ```jldoctest
 julia> prepend!([3],[1,2])
@@ -982,6 +991,10 @@ julia> prepend!([3],[1,2])
  2
  3
 ```
+
+Use [`unshift!`](@ref) to add individual items to `collection` which are not already
+themselves in another collection. The result is of the preceding example is equivalent to
+`unshift!([1, 2, 3], 4, 5, 6)`.
 """
 function prepend! end
 
@@ -1080,7 +1093,7 @@ end
 Remove an item in `collection` and return it. If `collection` is an
 ordered container, the last item is returned.
 
-See also: [`shift!`](@ref), [`splice!`](@ref)
+See also: [`shift!`](@ref), [`splice!`](@ref), [`push!`](@ref)
 
 # Examples
 ```jldoctest
@@ -1125,17 +1138,22 @@ end
 
 Insert one or more `items` at the beginning of `collection`.
 
+**See also:**
+[`push!`](@ref), [`insert`](@ref), [`shift!`](@ref)
+
 # Examples
 ```jldoctest
-julia> unshift!([1, 2, 3, 4], 5, 6)
+julia> unshift!([1, 2, 3], 4, 5, 6)
 6-element Array{Int64,1}:
+ 4
  5
  6
  1
  2
  3
- 4
 ```
+Use [`prepend!`](@ref) to add all the elements of another collection to
+`collection`. The result of the preceding example is equivalent to `prepend!([1, 2, 3], [4, 5, 6])`.
 """
 function unshift!(a::Array{T,1}, item) where T
     item = convert(T, item)
@@ -1149,7 +1167,7 @@ end
 
 Remove the first `item` from `collection`.
 
-See also: [`pop!`](@ref), [`splice!`](@ref)
+See also: [`pop!`](@ref), [`splice!`](@ref), [`unshift!`](@ref)
 
 # Examples
 ```jldoctest
@@ -1189,6 +1207,9 @@ end
 Insert an `item` into `a` at the given `index`. `index` is the index of `item` in
 the resulting `a`.
 
+**See also:**
+[`push!`](@ref), [`unshift!`](@ref),  [`splice!`](@ref)
+
 # Examples
 ```jldoctest
 julia> insert!([6, 5, 4, 2, 1], 4, 3)
@@ -1216,6 +1237,9 @@ end
 Remove the item at the given `i` and return the modified `a`. Subsequent items
 are shifted to fill the resulting gap.
 
+**See also:**
+[`splice!`](@ref)
+
 # Examples
 ```jldoctest
 julia> deleteat!([6, 5, 4, 3, 2, 1], 2)
@@ -1320,7 +1344,7 @@ Subsequent items are shifted left to fill the resulting gap.
 If specified, replacement values from an ordered
 collection will be spliced in place of the removed item.
 
-See also: [`pop!`](@ref), [`shift!`](@ref)
+See also: [`pop!`](@ref), [`shift!`](@ref), [`insert!`](@ref)
 
 # Examples
 ```jldoctest splice!

From 14a3f7411507babc07ec0efdfb74567d9d164d8e Mon Sep 17 00:00:00 2001
From: Christian Kurz <c.kurz@tu-bs.de>
Date: Fri, 22 Sep 2017 08:41:50 +0200
Subject: [PATCH 4/6] Added matching example, corrected sentence

I think the sentence is more clear, with out the "which are not already..." part.
---
 base/array.jl | 28 +++++++++++++++++-----------
 1 file changed, 17 insertions(+), 11 deletions(-)

diff --git a/base/array.jl b/base/array.jl
index 6f554099ccec4..abe02141dd10c 100644
--- a/base/array.jl
+++ b/base/array.jl
@@ -898,9 +898,8 @@ julia> push!([1, 2, 3], 4, 5, 6)
  6
 ```
 
-Use [`append!`](@ref) to add all the elements of another collection to
-`collection`. The result of the preceding example is equivalent to `append!([1, 2, 3], [4,
-5, 6])`.
+Use [`append!`](@ref) to add all the elements of another collection to `collection`.
+The result of the preceding example is equivalent to `append!([1, 2, 3], [4, 5, 6])`.
 """
 function push! end
 
@@ -944,9 +943,8 @@ julia> append!([1, 2, 3], [4, 5, 6])
  6
 ```
 
-Use [`push!`](@ref) to add individual items to `collection` which are not already
-themselves in another collection. The result is of the preceding example is equivalent to
-`push!([1, 2, 3], 4, 5, 6)`.
+Use [`push!`](@ref) to add individual items to `collection`. The result of
+the preceding example is equivalent to `push!([1, 2, 3], 4, 5, 6)`.
 """
 function append!(a::Array{<:Any,1}, items::AbstractVector)
     itemindices = eachindex(items)
@@ -990,11 +988,19 @@ julia> prepend!([3],[1,2])
  1
  2
  3
+
+julia> prepend!([1, 2, 3], [4, 5, 6])
+6-element Array{Int64,1}:
+ 4
+ 5
+ 6
+ 1
+ 2
+ 3
 ```
 
-Use [`unshift!`](@ref) to add individual items to `collection` which are not already
-themselves in another collection. The result is of the preceding example is equivalent to
-`unshift!([1, 2, 3], 4, 5, 6)`.
+Use [`unshift!`](@ref) to add individual items to `collection`. The result of
+the preceding example is equivalent to `unshift!([1, 2, 3], 4, 5, 6)`.
 """
 function prepend! end
 
@@ -1152,8 +1158,8 @@ julia> unshift!([1, 2, 3], 4, 5, 6)
  2
  3
 ```
-Use [`prepend!`](@ref) to add all the elements of another collection to
-`collection`. The result of the preceding example is equivalent to `prepend!([1, 2, 3], [4, 5, 6])`.
+Use [`prepend!`](@ref) to add all the elements of another collection to `collection`.
+The result of the preceding example is equivalent to `prepend!([1, 2, 3], [4, 5, 6])`.
 """
 function unshift!(a::Array{T,1}, item) where T
     item = convert(T, item)

From 9c3e3e1cd47bbec3e0a3bd31e38e52e79c0fb92d Mon Sep 17 00:00:00 2001
From: Christian Kurz <c.kurz@tu-bs.de>
Date: Mon, 25 Sep 2017 10:56:08 +0200
Subject: [PATCH 5/6] replaced additional descriptions with `See also:`-entry

I removed all descriptions of other functions and inserted an entry in `See also:` instead.
This is related to my first commits' proposal of using a link-description list as `See also:`.

I also removed the redundant description in `splice!` for removing items. I opted to remove it from the single-item method, as a (negative) range is used to remove items.
---
 base/array.jl | 38 ++++++++++----------------------------
 1 file changed, 10 insertions(+), 28 deletions(-)

diff --git a/base/array.jl b/base/array.jl
index abe02141dd10c..0ad4bade48348 100644
--- a/base/array.jl
+++ b/base/array.jl
@@ -362,6 +362,8 @@ Create an array of all zeros with the same layout as `A`, element type `T` and s
 The `A` argument can be skipped, which behaves like `Array{Float64,0}()` was passed.
 For convenience `dims` may also be passed in variadic form.
 
+See also: [`ones`](@ref), [`similar`](@ref)
+
 # Examples
 ```jldoctest
 julia> zeros(1)
@@ -394,7 +396,6 @@ julia> zeros(A, Bool, (3,))
  false
  false
 ```
-See also [`ones`](@ref), [`similar`](@ref).
 """
 function zeros end
 
@@ -405,6 +406,8 @@ Create an array of all ones with the same layout as `A`, element type `T` and si
 The `A` argument can be skipped, which behaves like `Array{Float64,0}()` was passed.
 For convenience `dims` may also be passed in variadic form.
 
+See also: [`zeros`](@ref), [`similar`](@ref)
+
 # Examples
 ```jldoctest
 julia> ones(Complex128, 2, 3)
@@ -437,7 +440,6 @@ julia> ones(A, Bool, (3,))
  true
  true
 ```
-See also [`zeros`](@ref), [`similar`](@ref).
 """
 function ones end
 
@@ -883,8 +885,7 @@ _deleteat!(a::Vector, i::Integer, delta::Integer) =
 
 Insert one or more `items` at the end of `collection`.
 
-**See also:**
-[`unshift!`](@ref), [`insert!`](@ref), [`pop!`](@ref)
+See also: [`append!`](@ref), [`unshift!`](@ref), [`insert!`](@ref), [`pop!`](@ref)
 
 # Examples
 ```jldoctest
@@ -897,9 +898,6 @@ julia> push!([1, 2, 3], 4, 5, 6)
  5
  6
 ```
-
-Use [`append!`](@ref) to add all the elements of another collection to `collection`.
-The result of the preceding example is equivalent to `append!([1, 2, 3], [4, 5, 6])`.
 """
 function push! end
 
@@ -922,8 +920,7 @@ end
 
 Add the elements of `items` to the end of `a`.
 
-**See also:**
-[`prepend!`](@ref), [`insert!`](@ref)
+See also: [`push!`](@ref), [`prepend!`](@ref), [`insert!`](@ref)
 
 # Examples
 ```jldoctest
@@ -942,9 +939,6 @@ julia> append!([1, 2, 3], [4, 5, 6])
  5
  6
 ```
-
-Use [`push!`](@ref) to add individual items to `collection`. The result of
-the preceding example is equivalent to `push!([1, 2, 3], 4, 5, 6)`.
 """
 function append!(a::Array{<:Any,1}, items::AbstractVector)
     itemindices = eachindex(items)
@@ -978,8 +972,7 @@ end
 
 Insert the elements of `items` to the beginning of `a`.
 
-**See also:**
-[`append!`](@ref), [`insert!`](@ref)
+See also: [`unshift!`](@ref), [`append!`](@ref), [`insert!`](@ref)
 
 # Examples
 ```jldoctest
@@ -998,9 +991,6 @@ julia> prepend!([1, 2, 3], [4, 5, 6])
  2
  3
 ```
-
-Use [`unshift!`](@ref) to add individual items to `collection`. The result of
-the preceding example is equivalent to `unshift!([1, 2, 3], 4, 5, 6)`.
 """
 function prepend! end
 
@@ -1144,8 +1134,7 @@ end
 
 Insert one or more `items` at the beginning of `collection`.
 
-**See also:**
-[`push!`](@ref), [`insert`](@ref), [`shift!`](@ref)
+See also: [`prepend!`](@ref), [`push!`](@ref), [`insert`](@ref), [`shift!`](@ref)
 
 # Examples
 ```jldoctest
@@ -1158,8 +1147,6 @@ julia> unshift!([1, 2, 3], 4, 5, 6)
  2
  3
 ```
-Use [`prepend!`](@ref) to add all the elements of another collection to `collection`.
-The result of the preceding example is equivalent to `prepend!([1, 2, 3], [4, 5, 6])`.
 """
 function unshift!(a::Array{T,1}, item) where T
     item = convert(T, item)
@@ -1213,8 +1200,7 @@ end
 Insert an `item` into `a` at the given `index`. `index` is the index of `item` in
 the resulting `a`.
 
-**See also:**
-[`push!`](@ref), [`unshift!`](@ref),  [`splice!`](@ref)
+See also: [`push!`](@ref), [`unshift!`](@ref),  [`splice!`](@ref)
 
 # Examples
 ```jldoctest
@@ -1243,8 +1229,7 @@ end
 Remove the item at the given `i` and return the modified `a`. Subsequent items
 are shifted to fill the resulting gap.
 
-**See also:**
-[`splice!`](@ref)
+See also: [`splice!`](@ref)
 
 # Examples
 ```jldoctest
@@ -1389,9 +1374,6 @@ julia> A
   3
  -1
 ```
-
-To insert `replacement` before an index `n` without removing any items, use
-`splice!(collection, n:n-1, replacement)`.
 """
 function splice!(a::Vector, i::Integer, ins=_default_splice)
     v = a[i]

From 751e348cf0408b2b026ca4d408fe5de569eeb0d4 Mon Sep 17 00:00:00 2001
From: Christian Kurz <c.kurz@tu-bs.de>
Date: Mon, 25 Sep 2017 11:46:33 +0200
Subject: [PATCH 6/6] removed duplicate examples, added `see also:` items for
 `deleteat!`

---
 base/array.jl | 22 ++--------------------
 1 file changed, 2 insertions(+), 20 deletions(-)

diff --git a/base/array.jl b/base/array.jl
index 0ad4bade48348..27203f5305957 100644
--- a/base/array.jl
+++ b/base/array.jl
@@ -929,15 +929,6 @@ julia> append!([1],[2,3])
  1
  2
  3
-
-julia> append!([1, 2, 3], [4, 5, 6])
-6-element Array{Int64,1}:
- 1
- 2
- 3
- 4
- 5
- 6
 ```
 """
 function append!(a::Array{<:Any,1}, items::AbstractVector)
@@ -981,15 +972,6 @@ julia> prepend!([3],[1,2])
  1
  2
  3
-
-julia> prepend!([1, 2, 3], [4, 5, 6])
-6-element Array{Int64,1}:
- 4
- 5
- 6
- 1
- 2
- 3
 ```
 """
 function prepend! end
@@ -1229,7 +1211,7 @@ end
 Remove the item at the given `i` and return the modified `a`. Subsequent items
 are shifted to fill the resulting gap.
 
-See also: [`splice!`](@ref)
+See also: [`splice!`](@ref), [`pop!`](@ref), [`unshift!`](@ref)
 
 # Examples
 ```jldoctest
@@ -1335,7 +1317,7 @@ Subsequent items are shifted left to fill the resulting gap.
 If specified, replacement values from an ordered
 collection will be spliced in place of the removed item.
 
-See also: [`pop!`](@ref), [`shift!`](@ref), [`insert!`](@ref)
+See also: [`pop!`](@ref), [`shift!`](@ref), [`insert!`](@ref), [`deleteat!`](@ref)
 
 # Examples
 ```jldoctest splice!