diff --git a/doc/manual/functions.rst b/doc/manual/functions.rst index 97ceba3e7a4c6..6f1128034e2d6 100644 --- a/doc/manual/functions.rst +++ b/doc/manual/functions.rst @@ -396,32 +396,31 @@ multiple method definitions with different numbers of arguments (see :ref:`man-methods`). -Named Arguments +Keyword Arguments --------------- Some functions need a large number of arguments, or have a large number of -behaviors. Remembering how to call such functions can be difficult. Named -arguments, also called keyword arguments, can make these complex interfaces -easier to use and extend by allowing arguments to be identified by name -instead of only by position. +behaviors. Remembering how to call such functions can be difficult. Keyword +arguments can make these complex interfaces easier to use and extend by +allowing arguments to be identified by name instead of only by position. For example, consider a function ``plot`` that plots a line. This function might have many options, for controlling line -style, width, color, and so on. If it accepts named arguments, a possible +style, width, color, and so on. If it accepts keyword arguments, a possible call might look like ``plot(x, y, width=2)``, where we have chosen to specify only line width. Notice that this serves two purposes. The call is easier to read, since we can label an argument with its meaning. It also becomes possible to pass any subset of a large number of arguments, in any order. -Functions with named arguments are defined using a semicolon in the +Functions with keyword arguments are defined using a semicolon in the signature:: function plot(x, y; style="solid", width=1, color="black") ### end -Extra named arguments can be collected using ``...``, as in varargs +Extra keyword arguments can be collected using ``...``, as in varargs functions:: function f(x; args...) @@ -429,7 +428,7 @@ functions:: end Inside ``f``, ``args`` will be a collection of ``(key,value)`` tuples, -where each ``key`` is a symbol. Such collections can be passed as named +where each ``key`` is a symbol. Such collections can be passed as keyword arguments using a semicolon in a call, ``f(x; k...)``. Dictionaries can be used for this purpose. diff --git a/doc/manual/methods.rst b/doc/manual/methods.rst index f223d9979be69..b7d2b95a4fe34 100644 --- a/doc/manual/methods.rst +++ b/doc/manual/methods.rst @@ -441,7 +441,7 @@ 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. -Note on Optional and Named Arguments +Note on Optional and keyword Arguments ------------------------------------ As mentioned briefly in :ref:`man-functions`, optional arguments are @@ -456,9 +456,9 @@ translates to the following three methods:: f(a) = f(a,2) f() = f(1,2) -Named arguments behave quite differently from ordinary positional arguments. +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 named arguments processed +dispatched based only on positional arguments, with keyword arguments processed after the matching method is identified. .. [Clarke61] Arthur C. Clarke, *Profiles of the Future* (1961): Clarke's Third Law. diff --git a/doc/manual/performance-tips.rst b/doc/manual/performance-tips.rst index fb062fb965b5a..10f3875f1003a 100644 --- a/doc/manual/performance-tips.rst +++ b/doc/manual/performance-tips.rst @@ -103,24 +103,24 @@ Here, we happened to know that the first element of ``a`` would be an will raise a run-time error if the value is not of the expected type, potentially catching certain bugs earlier. -Declare types of named arguments +Declare types of keyword arguments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Named arguments can have declared types:: +Keyword arguments can have declared types:: - function with_named(x; name::Int = 1) + function with_keyword(x; name::Int = 1) ... end -Functions are specialized on the types of named arguments, so these +Functions are specialized on the types of keyword arguments, so these declarations will not affect performance of code inside the function. However, they will reduce the overhead of calls to the function that -include named arguments. +include keyword arguments. -Functions with named arguments have near-zero overhead for call sites +Functions with keyword arguments have near-zero overhead for call sites that pass only positional arguments. -Passing dynamic lists of named arguments, as in ``f(x; names...)``, +Passing dynamic lists of keyword arguments, as in ``f(x; keywords...)``, can be slow and should be avoided in performance-sensitive code. Break functions into multiple definitions diff --git a/doc/stdlib/profile.rst b/doc/stdlib/profile.rst index eae7208b08823..b156a4cb723ec 100644 --- a/doc/stdlib/profile.rst +++ b/doc/stdlib/profile.rst @@ -215,7 +215,7 @@ Let's discuss these arguments in order: @profile Profile.print(STDOUT, data) # Prints the previous results Profile.print() # Prints results from Profile.print() -- The first named argument, ``format``, was introduced above. The +- The first keyword argument, ``format``, was introduced above. The possible choices are ``:tree`` and ``:flat``. - ``C``, if set to ``true``, allows you to see even the calls to C code. Try running the introductory example with ``Profile.print(C =