Add a few methods to manual & fix doctests (#32417)

* Don't share doctest state between docstrings

This is not, strictly speaking, well defined. There is no official rule
as to which docstring should get executed first.

This will not be supported in a future version of Documenter.

* Add Channel(::Function) to the manual

Also fix the doctest in the docstring. The simpler println variant seems
to be more reliable when printing from a another task (with at-show, the
"Hello" string did not actually get printed).

* Fix Base.splat doctest

The function is not exported.  Note that it does not currently get
doctested, but will be tested in a future Documenter version.

* Fix doctest in at-locals docstring

This is not currently included in the manual and therefore not
doctested, but will be in the future.

* Fix doctest in Base.isambiguous docstring

Not currently doctested since it is not included in the manual, but will
be in the future.

* Add findnext/last(::AbstractChar,...) to manual

Also fix a doctest in one of the docstrings.

* Add BLAS.dot and axpby! to manual

And fix the doctests in the docstrings.

* Fix doctests of unexported functions

Fix doctests in the docstrings of LinearAlgebra.isbanded, 
LinearAlgebra.promote_leaf_eltypes and SparseArrays.dropstored!. All the 
functions are unexported and not included in the manual.

They are currently not being doctested, but will be with a future 
version of Documenter.

Author: mortenpi

base/array.jl

@@ -1281,7 +1281,7 @@ If specified, replacement values from an ordered
 collection will be spliced in place of the removed item.
 
 # Examples
-```jldoctest splice!
+```jldoctest
 julia> A = [6, 5, 4, 3, 2, 1]; splice!(A, 5)
 2
 
@@ -1352,8 +1352,8 @@ To insert `replacement` before an index `n` without removing any items, use
 `splice!(collection, n:n-1, replacement)`.
 
 # Examples
-```jldoctest splice!
-julia> splice!(A, 4:3, 2)
+```jldoctest
+julia> A = [-1, -2, -3, 5, 4, 3, -1]; splice!(A, 4:3, 2)
 0-element Array{Int64,1}
 
 julia> A

base/channels.jl

@@ -84,13 +84,13 @@ Referencing the created task:
 ```jldoctest
 julia> taskref = Ref{Task}();
 
-julia> chnl = Channel(c->(@show take!(c)); taskref=taskref);
+julia> chnl = Channel(c -> println(take!(c)); taskref=taskref);
 
 julia> istaskdone(taskref[])
 false
 
 julia> put!(chnl, "Hello");
-take!(c) = "Hello"
+Hello
 
 julia> istaskdone(taskref[])
 true

base/operators.jl

@@ -1028,7 +1028,7 @@ passes a tuple as that single argument.
 
 # Example usage:
 ```jldoctest
-julia> map(splat(+), zip(1:3,4:6))
+julia> map(Base.splat(+), zip(1:3,4:6))
 3-element Array{Int64,1}:
  5
  7

base/reflection.jl

@@ -295,9 +295,9 @@ julia> function f(x)
        end;
 
 julia> f(42)
-Dict{Symbol,Any}(:x=>42)
-Dict{Symbol,Any}(:i=>1,:x=>42)
-Dict{Symbol,Any}(:y=>2,:x=>42)
+Dict{Symbol,Any}(:x => 42)
+Dict{Symbol,Any}(:i => 1,:x => 42)
+Dict{Symbol,Any}(:y => 2,:x => 42)
 ```
 """
 macro locals()
@@ -1274,7 +1274,7 @@ foo (generic function with 2 methods)
 julia> m1, m2 = collect(methods(foo));
 
 julia> typeintersect(m1.sig, m2.sig)
-Tuple{#foo,Complex{Union{}}}
+Tuple{typeof(foo),Complex{Union{}}}
 
 julia> Base.isambiguous(m1, m2, ambiguous_bottom=true)
 true

base/strings/search.jl

@@ -284,10 +284,10 @@ Find the next occurrence of character `ch` in `string` starting at position `sta
 
 # Examples
 ```jldoctest
-julia> findnext(`z`, "Hello to the world", 1) === nothing
+julia> findnext('z', "Hello to the world", 1) === nothing
 true
 
-julia> findnext(`o`, "Hello to the world", 6)
+julia> findnext('o', "Hello to the world", 6)
 8
 ```
 """

doc/src/base/parallel.md

@@ -44,6 +44,7 @@ Base.islocked
 Base.ReentrantLock
 
 Base.Channel
+Base.Channel(::Function)
 Base.put!(::Channel, ::Any)
 Base.take!(::Channel)
 Base.isready(::Channel)

doc/src/base/strings.md

@@ -39,7 +39,9 @@ Base.lpad
 Base.rpad
 Base.findfirst(::AbstractString, ::AbstractString)
 Base.findnext(::AbstractString, ::AbstractString, ::Integer)
+Base.findnext(::AbstractChar, ::AbstractString, ::Integer)
 Base.findlast(::AbstractString, ::AbstractString)
+Base.findlast(::AbstractChar, ::AbstractString)
 Base.findprev(::AbstractString, ::AbstractString, ::Integer)
 Base.occursin
 Base.reverse(::Union{String,SubString{String}})

stdlib/LinearAlgebra/docs/src/index.md

@@ -520,12 +520,14 @@ the input argument belongs on (`side`). The possibilities are:
 
 ```@docs
 LinearAlgebra.BLAS
+LinearAlgebra.BLAS.dot
 LinearAlgebra.BLAS.dotu
 LinearAlgebra.BLAS.dotc
 LinearAlgebra.BLAS.blascopy!
 LinearAlgebra.BLAS.nrm2
 LinearAlgebra.BLAS.asum
 LinearAlgebra.axpy!
+LinearAlgebra.axpby!
 LinearAlgebra.BLAS.scal!
 LinearAlgebra.BLAS.scal
 LinearAlgebra.BLAS.iamax

stdlib/LinearAlgebra/src/blas.jl

@@ -238,7 +238,7 @@ Dot product of two vectors consisting of `n` elements of array `X` with stride `
 
 # Examples
 ```jldoctest
-julia> dot(10, fill(1.0, 10), 1, fill(1.0, 20), 2)
+julia> BLAS.dot(10, fill(1.0, 10), 1, fill(1.0, 20), 2)
 10.0
 ```
 """
@@ -495,9 +495,9 @@ julia> y = [4., 5, 6];
 
 julia> BLAS.axpby!(2., x, 3., y)
 3-element Array{Float64,1}:
-14.0
-19.0
-24.0
+ 14.0
+ 19.0
+ 24.0
 ```
 """
 function axpby! end

stdlib/LinearAlgebra/src/generic.jl

@@ -1183,21 +1183,21 @@ julia> a = [1 2; 2 -1]
  1   2
  2  -1
 
-julia> isbanded(a, 0, 0)
+julia> LinearAlgebra.isbanded(a, 0, 0)
 false
 
-julia> isbanded(a, -1, 1)
+julia> LinearAlgebra.isbanded(a, -1, 1)
 true
 
 julia> b = [1 0; -im -1] # lower bidiagonal
 2×2 Array{Complex{Int64},2}:
  1+0im   0+0im
  0-1im  -1+0im
 
-julia> isbanded(b, 0, 0)
+julia> LinearAlgebra.isbanded(b, 0, 0)
 false
 
-julia> isbanded(b, -1, 0)
+julia> LinearAlgebra.isbanded(b, -1, 0)
 true
 ```
 """
@@ -1423,7 +1423,7 @@ julia> a = [[1,2, [3,4]], 5.0, [6im, [7.0, 8.0]]]
  5.0
   Any[0+6im,[7.0,8.0]]
 
-julia> promote_leaf_eltypes(a)
+julia> LinearAlgebra.promote_leaf_eltypes(a)
 Complex{Float64}
 ```
 """

stdlib/SparseArrays/src/sparsevector.jl

@@ -325,11 +325,11 @@ julia> x = sparsevec([1, 3], [1.0, 2.0])
   [1]  =  1.0
   [3]  =  2.0
 
-julia> Base.SparseArrays.dropstored!(x, 3)
+julia> SparseArrays.dropstored!(x, 3)
 3-element SparseVector{Float64,Int64} with 1 stored entry:
   [1]  =  1.0
 
-julia> Base.SparseArrays.dropstored!(x, 2)
+julia> SparseArrays.dropstored!(x, 2)
 3-element SparseVector{Float64,Int64} with 1 stored entry:
   [1]  =  1.0
 ```