Merge pull request #12835 from JuliaLang/jcb/docfixes

let's release this thing !

Author: jakebolewski

base/array.jl

@@ -241,6 +241,11 @@ convert{T,n,S}(::Type{Array{T,n}}, x::Array{S,n}) = copy!(similar(x,T), x)
 
 promote_rule{T,n,S}(::Type{Array{T,n}}, ::Type{Array{S,n}}) = Array{promote_type(T,S),n}
 
+"""
+    collect(element_type, collection)
+
+Return an array of type `Array{element_type,1}` of all items in a collection.
+"""
 function collect{T}(::Type{T}, itr)
     if applicable(length, itr)
         # when length() isn't defined this branch might pollute the
@@ -259,6 +264,11 @@ function collect{T}(::Type{T}, itr)
     return a
 end
 
+"""
+    collect(collection)
+
+Return an array of all items in a collection. For associative collections, returns (key, value) tuples.
+"""
 collect(itr) = collect(eltype(itr), itr)
 
 ## Iteration ##

base/docs/Docs.jl

@@ -104,10 +104,13 @@ end
 
 function signature(expr::Expr)
     if isexpr(expr, :call)
-        sig = :(Tuple{})
+        sig = :(Union{Tuple{}})
         for arg in expr.args[2:end]
             isexpr(arg, :parameters) && continue
-            push!(sig.args, argtype(arg))
+            if isa(arg,Expr) && arg.head === :kw # optional arg
+                push!(sig.args, :(Tuple{$(sig.args[end].args...)}))
+            end
+            push!(sig.args[end].args, argtype(arg))
         end
         Expr(:let, Expr(:block, sig), typevars(expr)...)
     else
@@ -133,50 +136,58 @@ tvar(s::Symbol) = :($(s) = TypeVar($(quot(s)), Any, true))
 
 type FuncDoc
     main
-    order::Vector{Method}
+    order::Vector{Type}
     meta::ObjectIdDict
     source::ObjectIdDict
 end
 
 FuncDoc() = FuncDoc(nothing, [], ObjectIdDict(), ObjectIdDict())
 
+# handles the :(function foo end) form
 function doc!(f::Function, data)
-    fd = get!(meta(), f, FuncDoc())
-    fd.main = data
+    doc!(f, Union{}, data, nothing)
 end
 
-function doc!(f::Function, m::Method, data, source)
+type_morespecific(a::Type, b::Type) =
+    (ccall(:jl_type_morespecific, Int32, (Any,Any), a, b) > 0)
+
+# handles the :(function foo(x...); ...; end) form
+function doc!(f::Function, sig::ANY, data, source)
     fd = get!(meta(), f, FuncDoc())
     isa(fd, FuncDoc) || error("Can't document a method when the function already has metadata")
-    !haskey(fd.meta, m) && push!(fd.order, m)
-    fd.meta[m] = data
-    fd.source[m] = source
+    haskey(fd.meta, sig) || push!(fd.order, sig)
+    sort!(fd.order, lt=type_morespecific)
+    fd.meta[sig] = data
+    fd.source[sig] = source
 end
 
-function doc(f::Function)
-    docs = []
+doc(f::Function) = doc(f, Tuple)
+
+function doc(f::Function, sig::Type)
+    isgeneric(f) && isempty(methods(f,sig)) && return nothing
     for mod in modules
-        if haskey(meta(mod), f)
+        if (haskey(meta(mod),f) && isa(meta(mod)[f],FuncDoc))
             fd = meta(mod)[f]
-            length(docs) == 0 && fd.main !== nothing && push!(docs, fd.main)
-            if isa(fd, FuncDoc)
-                for m in fd.order
-                    push!(docs, fd.meta[m])
+            results = []
+            for msig in fd.order
+                # try to find specific matching method signatures
+                if sig <: msig
+                    push!(results, (msig,fd.meta[msig]))
                 end
-            elseif length(docs) == 0
-                return fd
+            end
+            # if all method signatures are Union{} ( ⊥ ), concat all docstrings
+            if isempty(results)
+                return catdoc([fd.meta[msig] for msig in reverse(fd.order)]...)
+            else
+                sort!(results, lt=(a,b)->type_morespecific(first(a),first(b)))
+                return catdoc([last(r) for r in results]...)
             end
         end
     end
-    return catdoc(docs...)
+    return nothing
 end
+doc(f::Function,args::Any...) = doc(f, Tuple{args...})
 
-function doc(f::Function, m::Method)
-    for mod in modules
-        haskey(meta(mod), f) && isa(meta(mod)[f], FuncDoc) && haskey(meta(mod)[f].meta, m) &&
-            return meta(mod)[f].meta[m]
-    end
-end
 
 """
 `catdoc(xs...)`: Combine the documentation metadata `xs` into a single meta object.
@@ -209,7 +220,7 @@ end
 type TypeDoc
     main
     fields::Dict{Symbol, Any}
-    order::Vector{Method}
+    order::Vector{Type}
     meta::ObjectIdDict
 end
 
@@ -221,11 +232,11 @@ function doc!(t::DataType, data, fields)
     td.fields = fields
 end
 
-function doc!(f::DataType, m::Method, data, source)
+function doc!(f::DataType, sig::ANY, data, source)
     td = get!(meta(), f, TypeDoc())
     isa(td, TypeDoc) || error("Can't document a method when the type already has metadata")
-    !haskey(td.meta, m) && push!(td.order, m)
-    td.meta[m] = data
+    !haskey(td.meta, sig) && push!(td.order, sig)
+    td.meta[sig] = data
 end
 
 function doc(f::DataType)
@@ -251,19 +262,17 @@ isfield(x) = isexpr(x, :.) &&
   isexpr(x.args[2], QuoteNode, :quote)
 
 function fielddoc(T, k)
-  for mod in modules
-    if haskey(meta(mod), T) && isa(meta(mod)[T], TypeDoc) && haskey(meta(mod)[T].fields, k)
-      return meta(mod)[T].fields[k]
-    end
+    for mod in modules
+        if haskey(meta(mod), T) && isa(meta(mod)[T], TypeDoc) && haskey(meta(mod)[T].fields, k)
+            return meta(mod)[T].fields[k]
+        end
   end
   Text(sprint(io -> (print(io, "$T has fields: ");
                      print_joined(io, fieldnames(T), ", ", " and "))))
 end
 
 # Generic Callables
 
-doc(f, ::Method) = doc(f)
-
 # Modules
 
 function doc(m::Module)
@@ -318,11 +327,10 @@ end
 
 function funcdoc(meta, def, def′)
     f = esc(namify(def′))
-    m = :(methods($f, $(esc(signature(def′))))[end])
     quote
         @init
         $(esc(def))
-        doc!($f, $m, $(mdify(meta)), $(esc(quot(def′))))
+        doc!($f, $(esc(signature(def′))), $(mdify(meta)), $(esc(quot(def′))))
         $f
     end
 end
@@ -400,11 +408,7 @@ end
 
 function findmethod(ex)
     f = esc(namify(ex.args[1]))
-    if any(x -> isexpr(x, :(::)), ex.args)
-        :(doc($f, methods($f, $(esc(signature(ex))))[1]))
-    else
-        :(doc($f, @which($(esc(ex)))))
-    end
+    :(doc($f, $(esc(signature(ex)))))
 end
 
 # Swap out the bootstrap macro with the real one

base/docs/basedocs.jl

@@ -218,10 +218,20 @@ keywords[symbol(";")] = doc"""
     interfaces.
   """
 
+keywords[:(&&)]  = doc"""
+    x && y
+
+Short-circuiting boolean AND
+"""
+
+keywords[:(||)]  = doc"""
+    x || y
+
+Short-circuiting boolean OR
+"""
+
 keywords[:ccall] = doc"""
-      ccall((symbol, library) or function_pointer, ReturnType,
-            (ArgumentType1, ...),
-            ArgumentValue1, ...)
+      ccall((symbol, library) or function_pointer, ReturnType, (ArgumentType1, ...), ArgumentValue1, ...)
 
   Call function in C-exported shared library, specified by
   `(function name, library)` tuple, where each component is a string
@@ -297,6 +307,7 @@ keywords[:immutable] = doc"""
 # :@time
 
 doc"""
+    @r_str -> Regex
 Construct a regex, such as `r"^[a-z]*$"`. The regex also accepts
 one or more flags, listed after the ending quote, to change its
 behaviour:
@@ -327,7 +338,7 @@ For example, this regex has all three flags enabled:
 if Base.USE_GPL_LIBS
 
 @doc doc"""
-    fft(A[, dims])
+    fft(A [, dims])
 
 Performs a multidimensional FFT of the array `A`.  The optional
 `dims` argument specifies an iterable subset of dimensions (e.g.
@@ -355,7 +366,7 @@ processors.
 end # USE_GPL_LIBS
 
 """
-    include("file.jl")
+    include(path::AbstractString)
 
 Evaluate the contents of a source file in the current context.
 During including, a task-local include path is set to the directory
@@ -366,7 +377,7 @@ function is typically used to load source interactively, or to
 combine files in packages that are broken into multiple source
 files.
 """
-include_from_node1
+include_from_node1(::AbstractString)
 
 """
 0 (zero; BrE: `/ˈzɪərəʊ/` or AmE: `/ˈziːroʊ/`) is both a number and the numerical digit used to represent that number in numerals. It fulfills a central role in mathematics as the additive identity of the integers, real numbers, and many other algebraic structures. As a digit, 0 is used as a placeholder in place value systems. Names for the number 0 in English include zero, nought or (US) naught (`/ˈnɔːt/`), nil, or — in contexts where at least one adjacent digit distinguishes it from the letter "O" — oh or o (`/ˈoʊ/`). Informal or slang terms for zero include zilch and zip. Ought and aught (/ˈɔːt/), as well as cipher, have also been used historically.