Update methods.rst

doc/manual/functions.rst

@@ -448,7 +448,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