Merge pull request #13182 from JuliaLang/tk/backports3

[release-0.4] backports for RC2

CONTRIBUTING.md

@@ -88,7 +88,7 @@ If you want to edit the body of a method docstring, run the `doc/genstdlib.jl` s
 If you want to edit an existing docstring signature, you **first** have to change the signature in the `doc/stdlib` `..function` or `..data` definition (not the auto-generated content) and *then*
 edit the helpdb.jl or inline method docstrings. The existing signatures in the `doc/stdlib/*.rst` files are pattern matched to base docstrings and the new content overwrites the content in `doc/stdlib/`.
 The signature definitions **must** be in sync or else the pattern match will fail and documentation will be lost in the result.
-To add entirely new methods to the `stdlib` documentation, first add the signature in the appropriate `rst/stdlib/*.rst` file before writing the docstring, rebuilding Julia, and re-running `doc/genstdlib.jl`.
+To add entirely new methods to the `stdlib` documentation, first add the signature in the appropriate `doc/stdlib/*.rst` file before writing the docstring, rebuilding Julia, and re-running `doc/genstdlib.jl`.
 
 It is encouraged to write all new docstrings in Markdown markup. If you need to write a more complicated docstring that contains cross-references or citations it can be written in a restructured text codeblock.
 Many of the existing docstrings are currently restructured text codeblocks and these will be transitioned to Markdown over time. RST codeblocks are delineated with the triple-quote (\`\`\`rst \`\`\`) Makdown codeblock syntax.

Makefile

@@ -53,7 +53,7 @@ julia-deps: | $(DIRS) $(build_datarootdir)/julia/base $(build_datarootdir)/julia
 julia-base: julia-deps $(build_sysconfdir)/julia/juliarc.jl $(build_man1dir)/julia.1
  @$(MAKE) $(QUIET_MAKE) -C base
 
-julia-libccalltest:
+julia-libccalltest: julia-deps
  @$(MAKE) $(QUIET_MAKE) -C src libccalltest
 
 julia-src-release julia-src-debug : julia-src-% : julia-deps

base/deprecated.jl

@@ -107,7 +107,7 @@ deprecate(m::Module, s::Symbol) = ccall(:jl_deprecate_binding, Void, (Any, Any),
 macro deprecate_binding(old, new)
  Expr(:toplevel,
  Expr(:export, esc(old)),
- Expr(:(=), esc(old), esc(new)),
+ Expr(:const, Expr(:(=), esc(old), esc(new))),
  Expr(:call, :deprecate, Expr(:quote, old)))
 end
 
@@ -825,3 +825,5 @@ end
 end
 
 @deprecate cartesianmap(f, dims) for idx in CartesianRange(dims); f(idx.I...); end
+
+@deprecate Union(args...) Union{args...}

base/dft.jl

@@ -39,6 +39,170 @@ for f in (:fft, :bfft, :ifft, :fft!, :bfft!, :ifft!, :rfft)
  end
 end
 
+doc"""
+```rst
+.. plan_ifft(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf)
+
+Same as :func:`plan_fft`, but produces a plan that performs inverse transforms
+:func:`ifft`.
+```
+"""
+plan_ifft
+
+doc"""
+```rst
+.. plan_ifft!(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf)
+
+Same as :func:`plan_ifft`, but operates in-place on ``A``.
+```
+"""
+plan_ifft!
+
+doc"""
+```rst
+.. plan_bfft!(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf)
+
+Same as :func:`plan_bfft`, but operates in-place on ``A``.
+```
+"""
+plan_bfft!
+
+doc"""
+```rst
+.. plan_bfft(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf)
+
+Same as :func:`plan_fft`, but produces a plan that performs an unnormalized
+backwards transform :func:`bfft`.
+```
+"""
+plan_bfft
+
+doc"""
+```rst
+.. plan_fft(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf)
+
+Pre-plan an optimized FFT along given dimensions (``dims``) of arrays
+matching the shape and type of ``A``. (The first two arguments have
+the same meaning as for :func:`fft`.) Returns an object ``P`` which
+represents the linear operator computed by the FFT, and which contains
+all of the information needed to compute ``fft(A, dims)`` quickly.
+
+To apply ``P`` to an array ``A``, use ``P * A``; in general, the
+syntax for applying plans is much like that of matrices. (A plan
+can only be applied to arrays of the same size as the ``A`` for
+which the plan was created.) You can also apply a plan with a
+preallocated output array ``Â`` by calling ``A_mul_B!(Â, plan,
+A)``. You can compute the inverse-transform plan by ``inv(P)`` and
+apply the inverse plan with ``P \ Â`` (the inverse plan is cached
+and reused for subsequent calls to ``inv`` or ``\``), and apply the
+inverse plan to a pre-allocated output array ``A`` with
+``A_ldiv_B!(A, P, Â)``.
+
+The ``flags`` argument is a bitwise-or of FFTW planner flags, defaulting
+to ``FFTW.ESTIMATE``. e.g. passing ``FFTW.MEASURE`` or ``FFTW.PATIENT``
+will instead spend several seconds (or more) benchmarking different
+possible FFT algorithms and picking the fastest one; see the FFTW manual
+for more information on planner flags. The optional ``timelimit`` argument
+specifies a rough upper bound on the allowed planning time, in seconds.
+Passing ``FFTW.MEASURE`` or ``FFTW.PATIENT`` may cause the input array ``A``
+to be overwritten with zeros during plan creation.
+
+:func:`plan_fft!` is the same as :func:`plan_fft` but creates a plan
+that operates in-place on its argument (which must be an array of
+complex floating-point numbers). :func:`plan_ifft` and so on
+are similar but produce plans that perform the equivalent of
+the inverse transforms :func:`ifft` and so on.
+```
+"""
+plan_fft
+
+doc"""
+```rst
+.. plan_fft!(A [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf)
+
+Same as :func:`plan_fft`, but operates in-place on ``A``.
+```
+"""
+plan_fft!
+
+doc"""
+```rst
+.. rfft(A [, dims])
+
+Multidimensional FFT of a real array ``A``, exploiting the fact that
+the transform has conjugate symmetry in order to save roughly half
+the computational time and storage costs compared with :func:`fft`.
+If ``A`` has size ``(n_1, ..., n_d)``, the result has size
+``(div(n_1,2)+1, ..., n_d)``.
+
+The optional ``dims`` argument specifies an iterable subset of one or
+more dimensions of ``A`` to transform, similar to :func:`fft`. Instead
+of (roughly) halving the first dimension of ``A`` in the result, the
+``dims[1]`` dimension is (roughly) halved in the same way.
+```
+"""
+rfft
+
+doc"""
+```rst
+.. ifft!(A [, dims])
+
+Same as :func:`ifft`, but operates in-place on ``A``.
+```
+"""
+ifft!
+
+doc"""
+ ifft(A [, dims])
+
+Multidimensional inverse FFT.
+
+A one-dimensional inverse FFT computes
+
+$$\operatorname{IDFT}(A)[k] = \frac{1}{\operatorname{length}(A)}
+\sum_{n=1}^{\operatorname{length}(A)} \exp\left(+i\frac{2\pi (n-1)(k-1)}
+{\operatorname{length}(A)} \right) A[n].$$
+
+A multidimensional inverse FFT simply performs this operation along each transformed dimension of `A`.
+"""
+ifft
+
+doc"""
+```rst
+.. fft!(A [, dims])
+
+Same as :func:`fft`, but operates in-place on ``A``,
+which must be an array of complex floating-point numbers.
+```
+"""
+fft!
+
+doc"""
+```rst
+.. bfft(A [, dims])
+
+Similar to :func:`ifft`, but computes an unnormalized inverse (backward)
+transform, which must be divided by the product of the sizes of the
+transformed dimensions in order to obtain the inverse. (This is slightly
+more efficient than :func:`ifft` because it omits a scaling step, which in
+some applications can be combined with other computational steps elsewhere.)
+
+.. math::
+
+ \operatorname{BDFT}(A)[k] = \operatorname{length}(A) \operatorname{IDFT}(A)[k]
+```
+"""
+bfft
+
+doc"""
+```rst
+.. bfft!(A [, dims])
+
+Same as :func:`bfft`, but operates in-place on ``A``.
+```
+"""
+bfft!
+
 # promote to a complex floating-point type (out-of-place only),
 # so implementations only need Complex{Float} methods
 for f in (:fft, :bfft, :ifft)
@@ -142,6 +306,36 @@ for f in (:brfft, :irfft)
  end
 end
 
+doc"""
+```rst
+.. irfft(A, d [, dims])
+
+Inverse of :func:`rfft`: for a complex array ``A``, gives the
+corresponding real array whose FFT yields ``A`` in the first half.
+As for :func:`rfft`, ``dims`` is an optional subset of dimensions
+to transform, defaulting to ``1:ndims(A)``.
+
+``d`` is the length of the transformed real array along the ``dims[1]``
+dimension, which must satisfy ``div(d,2)+1 == size(A,dims[1])``.
+(This parameter cannot be inferred from ``size(A)`` since both
+``2*size(A,dims[1])-2`` as well as ``2*size(A,dims[1])-1`` are valid sizes
+for the transformed real array.)
+```
+"""
+irfft
+
+doc"""
+```rst
+.. brfft(A, d [, dims])
+
+Similar to :func:`irfft` but computes an unnormalized inverse transform
+(similar to :func:`bfft`), which must be divided by the product
+of the sizes of the transformed dimensions (of the real output array)
+in order to obtain the inverse transform.
+```
+"""
+brfft
+
 function rfft_output_size(x::AbstractArray, region)
  d1 = first(region)
  osize = [size(x)...]
@@ -161,26 +355,65 @@ plan_irfft{T}(x::AbstractArray{Complex{T}}, d::Integer, region; kws...) =
  ScaledPlan(plan_brfft(x, d, region; kws...),
  normalization(T, brfft_output_size(x, d, region), region))
 
+doc"""
+```rst
+.. plan_irfft(A, d [, dims]; flags=FFTW.ESTIMATE; timelimit=Inf)
+
+Pre-plan an optimized inverse real-input FFT, similar to :func:`plan_rfft`
+except for :func:`irfft` and :func:`brfft`, respectively. The first
+three arguments have the same meaning as for :func:`irfft`.
+```
+"""
+plan_irfft
+
 ##############################################################################
 
 export fftshift, ifftshift
 
 fftshift(x) = circshift(x, div([size(x)...],2))
 
+doc"""
+ fftshift(x)
+
+Swap the first and second halves of each dimension of `x`.
+"""
+fftshift(x)
+
 function fftshift(x,dim)
  s = zeros(Int,ndims(x))
  s[dim] = div(size(x,dim),2)
  circshift(x, s)
 end
 
+doc"""
+ fftshift(x,dim)
+
+Swap the first and second halves of the given dimension of array `x`.
+"""
+fftshift(x,dim)
+
 ifftshift(x) = circshift(x, div([size(x)...],-2))
 
+doc"""
+ ifftshift(x)
+
+Undoes the effect of `fftshift`.
+"""
+ifftshift
+
 function ifftshift(x,dim)
  s = zeros(Int,ndims(x))
  s[dim] = -div(size(x,dim),2)
  circshift(x, s)
 end
 
+doc"""
+ ifftshift(x, [dim])
+
+Undoes the effect of `fftshift`.
+"""
+ifftshift
+
 ##############################################################################
 
 # FFTW module (may move to an external package at some point):

base/docs/basedocs.jl

@@ -70,6 +70,61 @@ keywords[:export] = doc"""
  Test.bar(1) # 1
  """
 
+keywords[:abstract] = doc"""
+ `abstract` declares a type that cannot be instantiated, and serves only as a node in the type graph,
+ thereby describing sets of related concrete types: those concrete types which are their descendants.
+ Abstract types form the conceptual hierarchy which makes Julia’s type system more than just a collection of object implementations.
+ For example:
+
+ abstract Number
+ abstract Real <: Number
+
+ `abstract Number` has no supertype, whereas `abstract Real` is an abstract subtype of `Number`.
+ """
+
+keywords[:module] = doc"""
+ `module` declares a Module, which is a separate global variable workspace. Within a module, you can control which names from other modules are visible (via importing), and specify which of your names are intended to be public (via exporting). For example:
+
+ module
+ import Base.show
+ export MyType, foo
+
+ type MyType
+ x
+ end
+
+ bar(x) = 2x
+ foo(a::MyType) = bar(a.x) + 1
+ show(io, a::MyType) = print(io, "MyType $(a.x)")
+ end
+
+ Modules allow you to create top-level definitions without worrying about name conflicts when your code is used together with somebody else’s.
+ """
+
+keywords[:baremodule] = doc"""
+ `baremodule` declares a module that does not contain `using Base`, `import Base.call`,
+ or a definition of `eval`. It does still import `Core`.
+ """
+
+keywords[:bitstype] = doc"""
+ `bitstype` declares a concrete type whose data consists of plain old bits. Classic examples of bits types are integers and floating-point values. Some example built-in bits type declarations:
+
+ bitstype 32 Char
+ bitstype 8 Bool <: Integer
+
+ The first parameter indicates how many bits of storage the type requires. Currently, only sizes that are multiples of 8 bits are supported. The second parameter gives the name of the type. The `Bool` declaration shows how a bits type can be optionally declared to be a subtype of some supertype.
+ """
+
+keywords[:macro] = doc"""
+ `macro` defines a method to include generated code in the final body of a program. A macro maps a tuple of arguments to a returned expression, and the resulting expression is compiled directly rather than requiring a runtime `eval()` call. Macro arguments may include expressions, literal values, and symbols. For example:
+
+ macro sayhello(name)
+ return :( println("Hello, ", $name) )
+ end
+
+ This macro takes one argument: `name`. When `@sayhello` is encountered, the quoted expression is expanded to interpolate the value of the argument into the final expression.
+ """
+
 keywords[:const] = doc"""
  `const` is used to declare global variables which are also constant.
  In almost all code (and particularly performance sensitive code)