Merge branch 'daanhb-patch-1'

doc/helpdb.jl

@@ -90,7 +90,7 @@ Any[
    linear indexing behaviors should define \"linearindexing\" in the
    type-domain:
 
-   Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast()
+      Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast()
 
 "),
 
@@ -1368,11 +1368,20 @@ Any[
 
 "),
 
+("Base","which","which(symbol)
+
+   Return the module in which the binding for the variable referenced
+   by \"symbol\" was created.
+
+"),
+
 ("Base","@which","@which()
 
-   Evaluates the arguments to the specified function call, and returns
-   the \"Method\" object for the method that would be called for those
-   arguments.
+   Applied to a function call, it evaluates the arguments to the
+   specified function call, and returns the \"Method\" object for the
+   method that would be called for those arguments.  Applied to a
+   variable, it returns the module in which the variable was bound. It
+   calls out to the \"which\" function.
 
 "),
 
@@ -5175,11 +5184,12 @@ Millisecond(v)
 ("Base","cp","cp(src::AbstractString, dst::AbstractString; remove_destination::Bool=false, follow_symlinks::Bool=false)
 
    Copy the file, link, or directory from *src* to *dest*.
-   \"remove_destination=true\" will first remove an existing `dst`.
+   \"remove_destination=true\" will first remove an existing *dst*.
 
-   If `follow_symlinks=false`, and src is a symbolic link, dst will be created as a symbolic link.
-   If `follow_symlinks=true` and src is a symbolic link, dst will be a copy of the file or directory
-   `src` refers to.
+   If *follow_symlinks=false*, and src is a symbolic link, dst will be
+   created as a symbolic link. If *follow_symlinks=true* and src is a
+   symbolic link, dst will be a copy of the file or directory *src*
+   refers to.
 
 "),
 

doc/manual/arrays.rst

@@ -239,6 +239,7 @@ innermost array being indexed.
 
 Alternatively, single elements of a multidimensional array can be indexed as
 ::
+
     x = A[I]
 
 where ``I`` is a ``CartesianIndex``, effectively an ``n``-tuple of integers.

doc/manual/functions.rst

@@ -450,7 +450,7 @@ specified:
 
 Optional arguments are actually just a convenient syntax for writing
 multiple method definitions with different numbers of arguments
-(see :ref:`man-methods`).
+(see :ref:`man-note-on-optional-and-keyword-arguments`).
 
 
 Keyword Arguments

doc/manual/methods.rst

@@ -523,6 +523,8 @@ can also constrain type parameters of methods::
 The ``same_type_numeric`` function behaves much like the ``same_type``
 function defined above, but is only defined for pairs of numbers.
 
+.. _man-note-on-optional-and-keyword-arguments:
+
 Note on Optional and keyword Arguments
 --------------------------------------
 
@@ -538,6 +540,19 @@ translates to the following three methods::
     f(a) = f(a,2)
     f() = f(1,2)
 
+This means that calling ``f()`` is equivalent to calling ``f(1,2)``. In
+this case the result is ``5``, because ``f(1,2)`` invokes the first
+method of ``f`` above. However, this need not always be the case. If you
+define a fourth method that is more specialized for integers::
+
+    f(a::Int,b::Int) = a-2b
+
+then the result of both ``f()`` and ``f(1,2)`` is ``-3``. In other words,
+optional arguments are tied to a function, not to any specific method of
+that function. It depends on the types of the optional arguments which
+method is invoked. When optional arguments are defined in terms of a global
+variable, the type of the optional argument may even change at run-time.
+
 Keyword arguments behave quite differently from ordinary positional arguments.
 In particular, they do not participate in method dispatch. Methods are
 dispatched based only on positional arguments, with keyword arguments processed

doc/manual/types.rst

@@ -917,7 +917,7 @@ function itself. The salient aspects of a function's arguments are their
 order and their types. Therefore a tuple type is similar to a
 parameterized immutable type where each parameter is the type
 of one field. For example, a 2-element tuple type resembles the following
-immutable type:
+immutable type::
 
     immutable Tuple2{A,B}
       a::A

doc/stdlib/arrays.rst

@@ -65,7 +65,7 @@ Basic functions
 
    An abstract array subtype ``MyArray`` that wishes to opt into fast linear indexing behaviors should define ``linearindexing`` in the type-domain::
 
-   Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast()
+       Base.linearindexing{T<:MyArray}(::Type{T}) = Base.LinearFast()
 
 .. function:: countnz(A)