improve docs for IOContext. fixes #16763

also remove some references to the removed `multiline` property

base/docs/helpdb/Base.jl

@@ -6294,6 +6294,9 @@ defining a 2-argument `show(stream::IO, x::MyType)` method.
 Technically, the `MIME"mime"` macro defines a singleton type for the given `mime` string,
 which allows us to exploit Julia's dispatch mechanisms in determining how to display objects
 of any given type.
+
+The first argument to `show` can be an `IOContext` specifying output format properties.
+See `IOContext` for details.
 """
 show(stream, mime, x)
 

base/multimedia.jl

@@ -47,7 +47,7 @@ mimewritable(m::AbstractString, x) = mimewritable(MIME(m), x)
 # format and is returned unmodified.  This is useful so that raw data can be
 # passed to display(m::MIME, x).
 
-verbose_show(io, m, x) = show(IOContext(io,multiline=true,limit=false), m, x)
+verbose_show(io, m, x) = show(IOContext(io,limit=false), m, x)
 
 macro textmime(mime)
     quote

base/show.jl

@@ -2,6 +2,14 @@
 
 print(io::IO, s::Symbol) = (write(io,s); nothing)
 
+"""
+    IOContext
+
+IOContext provides a mechanism for passing output configuration settings among `show` methods.
+
+In short, it is an immutable dictionary that is a subclass of IO. It supports standard
+dictionary operations such as `getindex`, and can also be used as an I/O stream.
+"""
 immutable IOContext{IO_t <: IO} <: AbstractPipe
     io::IO_t
     dict::ImmutableDict{Symbol, Any}
@@ -11,28 +19,6 @@ immutable IOContext{IO_t <: IO} <: AbstractPipe
     end
 end
 
-"""
-    IOContext{<:IO} <: IO
-
-IOContext provides a mechanism for passing output-configuration keyword arguments through arbitrary show methods.
-
-In short, it is an immutable Dictionary that is a subclass of IO.
-
-    IOContext(io::IO, KV::Pair)
-
-Create a new entry in the IO Dictionary for the key => value pair
-
- - use `(key => value) in dict` to see if this particular combination is in the properties set
- - use `get(dict, key, default)` to retrieve the most recent value for a particular key
-
-```
-IOContext(io::IO, context::IOContext)
-```
-
-Create a IOContext that wraps an alternate IO but inherits the keyword arguments from the context
-"""
-IOContext
-
 IOContext(io::IO; kws...) = IOContext(IOContext(io, ImmutableDict{Symbol,Any}()); kws...)
 function IOContext(io::IOContext; kws...)
     for (k, v) in kws
@@ -48,7 +34,31 @@ IOContext(io::IO, key, value) = IOContext(io, ImmutableDict{Symbol, Any}(key, va
 IOContext(io::IOContext, key, value) = IOContext(io, ImmutableDict{Symbol, Any}(io.dict, key, value))
 
 IOContext(io::IO, context::IO) = IOContext(io)
+
+"""
+    IOContext(io::IO, context::IOContext)
+
+Create a IOContext that wraps an alternate IO but inherits the properties of `context`.
+"""
 IOContext(io::IO, context::IOContext) = IOContext(io, context.dict)
+
+"""
+    IOContext(io::IO, KV::Pair)
+
+Create an `IOContext` that wraps a given stream, adding the specified key=>value pair to
+the properties of that stream (note that `io` can itself be an `IOContext`).
+
+ - use `(key => value) in dict` to see if this particular combination is in the properties set
+ - use `get(dict, key, default)` to retrieve the most recent value for a particular key
+
+The following properties are in common use:
+
+ - `:compact`: Boolean specifying that small values should be printed more compactly, e.g.
+   that numbers should be printed with fewer digits. This is set when printing array
+   elements.
+ - `:limit`: Boolean specifying that containers should be truncated, e.g. showing `…` in
+   place of most elements.
+"""
 IOContext(io::IO, KV::Pair) = IOContext(io, KV[1], KV[2])
 
 show(io::IO, ctx::IOContext) = (print(io, "IOContext("); show(io, ctx.io); print(io, ")"))
@@ -1561,7 +1571,6 @@ function showarray(io::IO, X::AbstractArray, repr::Bool = true; header = true)
     if repr && ndims(X) == 1
         return show_vector(io, X, "[", "]")
     end
-    io = IOContext(io, multiline=false)
     if !haskey(io, :compact)
         io = IOContext(io, compact=true)
     end

doc/stdlib/io-network.rst

@@ -398,28 +398,33 @@ General I/O
 
    Read all available data on the stream, blocking the task only if no data is available. The result is a ``Vector{UInt8,1}``\ .
 
-.. function:: IOContext{<:IO} <: IO
+.. type:: IOContext
 
    .. Docstring generated from Julia source
 
-   IOContext provides a mechanism for passing output-configuration keyword arguments through arbitrary show methods.
+   IOContext provides a mechanism for passing output configuration settings among ``show`` methods.
 
-   In short, it is an immutable Dictionary that is a subclass of IO.
+   In short, it is an immutable dictionary that is a subclass of IO. It supports standard dictionary operations such as ``getindex``\ , and can also be used as an I/O stream.
 
-   .. code-block:: julia
+.. function:: IOContext(io::IO, KV::Pair)
 
-       IOContext(io::IO, KV::Pair)
+   .. Docstring generated from Julia source
 
-   Create a new entry in the IO Dictionary for the key => value pair
+   Create an ``IOContext`` that wraps a given stream, adding the specified key=>value pair to the properties of that stream (note that ``io`` can itself be an ``IOContext``\ ).
 
    * use ``(key => value) in dict`` to see if this particular combination is in the properties set
    * use ``get(dict, key, default)`` to retrieve the most recent value for a particular key
 
-   .. code-block:: julia
+   The following properties are in common use:
 
-       IOContext(io::IO, context::IOContext)
+   * ``:compact``\ : Boolean specifying that small values should be printed more compactly, e.g. that numbers should be printed with fewer digits. This is set when printing array elements.
+   * ``:limit``\ : Boolean specifying that containers should be truncated, e.g. showing ``…`` in place of most elements.
 
-   Create a IOContext that wraps an alternate IO but inherits the keyword arguments from the context
+.. function:: IOContext(io::IO, context::IOContext)
+
+   .. Docstring generated from Julia source
+
+   Create a IOContext that wraps an alternate IO but inherits the properties of ``context``\ .
 
 Text I/O
 --------
@@ -717,6 +722,8 @@ Julia environments (such as the IPython-based IJulia notebook).
 
    Technically, the ``MIME"mime"`` macro defines a singleton type for the given ``mime`` string, which allows us to exploit Julia's dispatch mechanisms in determining how to display objects of any given type.
 
+   The first argument to ``show`` can be an ``IOContext`` specifying output format properties. See ``IOContext`` for details.
+
 .. function:: mimewritable(mime, x)
 
    .. Docstring generated from Julia source

doc/stdlib/stacktraces.rst

@@ -17,7 +17,7 @@
    * ``func::Symbol``
 
      The name of the function containing the execution context.
-   * ``outer_linfo::Nullable{LambdaInfo}``
+   * ``linfo::Nullable{LambdaInfo}``
 
      The LambdaInfo containing the execution context (if it could be found).
    * ``file::Symbol``
@@ -26,15 +26,12 @@
    * ``line::Int``
 
      The line number in the file containing the execution context.
-   * ``inlined_file::Symbol``
-
-     The path to the file containing the context for inlined code.
-   * ``inlined_line::Int``
-
-     The line number in the file containing the context for inlined code.
    * ``from_c::Bool``
 
      True if the code is from C.
+   * ``inlined::Bool``
+
+     True if the code is from an inlined frame.
    * ``pointer::Int64``
 
      Representation of the pointer to the execution context as returned by ``backtrace``\ .