Merge pull request JuliaLang#14530 from hayd/rst

Remove last rst docstrings

base/collections.jl

@@ -61,8 +61,12 @@ end
 
 percolate_up!{T}(xs::AbstractArray{T}, i::Integer, o::Ordering) = percolate_up!(xs, i, xs[i], o)
 
+"""
+    heappop!(v, [ord])
 
-# Binary min-heap pop.
+Given a binary heap-ordered array, remove and return the lowest ordered element.
+For efficiency, this function does not check that the array is indeed heap-ordered.
+"""
 function heappop!(xs::AbstractArray, o::Ordering=Forward)
     x = xs[1]
     y = pop!(xs)
@@ -72,8 +76,12 @@ function heappop!(xs::AbstractArray, o::Ordering=Forward)
     x
 end
 
+"""
+    heappush!(v, x, [ord])
 
-# Binary min-heap push.
+Given a binary heap-ordered array, push a new element `x`, preserving the heap property.
+For efficiency, this function does not check that the array is indeed heap-ordered.
+"""
 function heappush!(xs::AbstractArray, x, o::Ordering=Forward)
     push!(xs, x)
     percolate_up!(xs, length(xs), x, o)
@@ -82,17 +90,30 @@ end
 
 
 # Turn an arbitrary array into a binary min-heap in linear time.
+"""
+    heapify!(v, [ord])
+
+In-place [`heapify`](:func:`heapify`).
+"""
 function heapify!(xs::AbstractArray, o::Ordering=Forward)
     for i in heapparent(length(xs)):-1:1
         percolate_down!(xs, i, o)
     end
     xs
 end
 
+"""
+    heapify(v, [ord])
+
+Returns a new vector in binary heap order, optionally using the given ordering.
+"""
 heapify(xs::AbstractArray, o::Ordering=Forward) = heapify!(copy(xs), o)
 
+"""
+    isheap(v, [ord])
 
-# Is an arbitrary array heap ordered?
+Return `true` if an array is heap-ordered according to the given order.
+"""
 function isheap(xs::AbstractArray, o::Ordering=Forward)
     for i in 1:div(length(xs), 2)
         if lt(o, xs[heapleft(i)], xs[i]) ||
@@ -107,9 +128,18 @@ end
 # PriorityQueue
 # -------------
 
-# A PriorityQueue that acts like a Dict, mapping values to their priorities,
-# with the addition of a dequeue! function to remove the lowest priority
-# element.
+"""
+    PriorityQueue(K, V, [ord])
+
+Construct a new [`PriorityQueue`](:obj:`PriorityQueue`), with keys of type
+`K` and values/priorites of type `V`.
+If an order is not given, the priority queue is min-ordered using
+the default comparison for `V`.
+
+A `PriorityQueue` acts like a `Dict`, mapping values to their
+priorities, with the addition of a `dequeue!` function to remove the
+lowest priority element.
+"""
 type PriorityQueue{K,V,O<:Ordering} <: Associative{K,V}
     # Binary heap of (element, priority) pairs.
     xs::Array{Pair{K,V}, 1}
@@ -168,8 +198,14 @@ PriorityQueue{K,V}(a::AbstractArray{Tuple{K,V}}, o::Ordering=Forward) = Priority
 length(pq::PriorityQueue) = length(pq.xs)
 isempty(pq::PriorityQueue) = isempty(pq.xs)
 haskey(pq::PriorityQueue, key) = haskey(pq.index, key)
-peek(pq::PriorityQueue) = pq.xs[1]
 
+"""
+    peek(pq)
+
+Return the lowest priority key from a priority queue without removing that
+key from the queue.
+"""
+peek(pq::PriorityQueue) = pq.xs[1]
 
 function percolate_down!(pq::PriorityQueue, i::Integer)
     x = pq.xs[i]
@@ -246,7 +282,11 @@ function setindex!{K,V}(pq::PriorityQueue{K, V}, value, key)
     value
 end
 
+"""
+    enqueue!(pq, k, v)
 
+Insert the a key `k` into a priority queue `pq` with priority `v`.
+"""
 function enqueue!{K,V}(pq::PriorityQueue{K,V}, key, value)
     if haskey(pq, key)
         throw(ArgumentError("PriorityQueue keys must be unique"))
@@ -257,7 +297,11 @@ function enqueue!{K,V}(pq::PriorityQueue{K,V}, key, value)
     pq
 end
 
+"""
+    dequeue!(pq)
 
+Remove and return the lowest priority key from a priority queue.
+"""
 function dequeue!(pq::PriorityQueue)
     x = pq.xs[1]
     y = pop!(pq.xs)

base/docs/helpdb.jl

@@ -5,7 +5,6 @@ import .Docs: keywords
 include("helpdb/BLAS.jl")
 include("helpdb/Libdl.jl")
 include("helpdb/Libc.jl")
-include("helpdb/Collections.jl")
 include("helpdb/Profile.jl")
 include("helpdb/Base.jl")
 include("helpdb/Dates.jl")

base/docs/helpdb/Base.jl

@@ -9928,7 +9928,7 @@ isvalid(::AbstractString,i)
     esc(e::ANY)
 
 Only valid in the context of an `Expr` returned from a macro. Prevents the macro hygiene
-pass from turning embedded variables into gensym variables. See the [marcro](:ref:`man-macros`)
+pass from turning embedded variables into gensym variables. See the [macro](:ref:`man-macros`)
 section of the Metaprogramming chapter of the manual for more details and examples.
 """
 esc

base/sparse/sparsematrix.jl

@@ -446,17 +446,14 @@ function sprand_IJ(r::AbstractRNG, m::Integer, n::Integer, density::AbstractFloa
 end
 
 """
-```rst
-..  sprand([rng],m,[n],p::AbstractFloat,[rfn])
+    sprand([rng],m,[n],p::AbstractFloat,[rfn])
 
-Create a random length ``m`` sparse vector or ``m`` by ``n`` sparse matrix, in
+Create a random length `m` sparse vector or `m` by `n` sparse matrix, in
 which the probability of any element being nonzero is independently given by
-``p`` (and hence the mean density of nonzeros is also exactly ``p``). Nonzero
-values are sampled from the distribution specified by ``rfn``. The uniform
-distribution is used in case ``rfn`` is not specified. The optional ``rng``
-argument specifies a random number generator, see :ref:`Random Numbers
-<random-numbers>`.
-```
+`p` (and hence the mean density of nonzeros is also exactly `p`). Nonzero
+values are sampled from the distribution specified by `rfn`. The uniform
+distribution is used in case `rfn` is not specified. The optional `rng`
+argument specifies a random number generator, see [Random Numbers](:ref:`Random Numbers <random-numbers>`).
 """
 function sprand{T}(r::AbstractRNG, m::Integer, n::Integer, density::AbstractFloat,
                 rfn::Function, ::Type{T}=eltype(rfn(r,1)))

doc/stdlib/arrays.rst

@@ -925,13 +925,7 @@ dense counterparts. The following functions are specific to sparse arrays.
 
    .. Docstring generated from Julia source
 
-   Create a random length ``m`` sparse vector or ``m`` by ``n`` sparse matrix, in
-   which the probability of any element being nonzero is independently given by
-   ``p`` (and hence the mean density of nonzeros is also exactly ``p``). Nonzero
-   values are sampled from the distribution specified by ``rfn``. The uniform
-   distribution is used in case ``rfn`` is not specified. The optional ``rng``
-   argument specifies a random number generator, see :ref:`Random Numbers
-   <random-numbers>`.
+   Create a random length ``m`` sparse vector or ``m`` by ``n`` sparse matrix, in which the probability of any element being nonzero is independently given by ``p`` (and hence the mean density of nonzeros is also exactly ``p``\ ). Nonzero values are sampled from the distribution specified by ``rfn``\ . The uniform distribution is used in case ``rfn`` is not specified. The optional ``rng`` argument specifies a random number generator, see :ref:`Random Numbers <random-numbers>`\ .
 
 .. function:: sprandn(m[,n],p::AbstractFloat)
 

doc/stdlib/collections.rst

@@ -1287,9 +1287,9 @@ changed efficiently.
 
    .. Docstring generated from Julia source
 
-   Construct a new :obj:`PriorityQueue`, with keys of type ``K`` and values/priorites of
-   type ``V``. If an order is not given, the priority queue is min-ordered using
-   the default comparison for ``V``.
+   Construct a new :obj:`PriorityQueue`\ , with keys of type ``K`` and values/priorites of type ``V``\ . If an order is not given, the priority queue is min-ordered using the default comparison for ``V``\ .
+
+   A ``PriorityQueue`` acts like a ``Dict``\ , mapping values to their priorities, with the addition of a ``dequeue!`` function to remove the lowest priority element.
 
 .. function:: enqueue!(pq, k, v)
 
@@ -1343,19 +1343,19 @@ is used, so that elements popped from the heap are given in ascending order.
 
    .. Docstring generated from Julia source
 
-   Return a new vector in binary heap order, optionally using the given ordering.
+   Returns a new vector in binary heap order, optionally using the given ordering.
 
 .. function:: heapify!(v, [ord])
 
    .. Docstring generated from Julia source
 
-   In-place :func:`heapify`.
+   In-place :func:`heapify`\ .
 
 .. function:: isheap(v, [ord])
 
    .. Docstring generated from Julia source
 
-   Return ``true`` iff an array is heap-ordered according to the given order.
+   Return ``true`` if an array is heap-ordered according to the given order.
 
 .. function:: heappush!(v, x, [ord])