improve docs for IOContext. fixes JuliaLang#16763

also remove some references to the removed `multiline` property

base/docs/helpdb/Base.jl

@@ -6280,6 +6280,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}
@@ -12,27 +20,10 @@ immutable IOContext{IO_t <: IO} <: AbstractPipe
 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
+ IOContext(io::IO; properties...)
 
- - 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
+The same as `IOContext(io::IO, KV::Pair)`, but accepting properties as keyword arguments.
 """
-IOContext
-
 IOContext(io::IO; kws...) = IOContext(IOContext(io, ImmutableDict{Symbol,Any}()); kws...)
 function IOContext(io::IOContext; kws...)
  for (k, v) in kws
@@ -48,7 +39,34 @@ 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.
+ - `:displaysize`: A `Tuple{Int,Int}` giving the size in rows and columns to use for text
+ output. This can be used to override the display size for called functions, but to
+ get the size of the screen use the `displaysize` function.
+"""
 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, ")"))
@@ -1566,7 +1584,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,40 @@ 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.
+ * ``:displaysize``\ : A ``Tuple{Int,Int}`` giving the size in rows and columns to use for text output. This can be used to override the display size for called functions, but to get the size of the screen use the ``displaysize`` function.
+
+.. function:: IOContext(io::IO, context::IOContext)
+
+ .. Docstring generated from Julia source
 
- Create a IOContext that wraps an alternate IO but inherits the keyword arguments from the context
+ Create a IOContext that wraps an alternate IO but inherits the properties of ``context``\ .
+
+.. function:: IOContext(io::IO; properties...)
+
+ .. Docstring generated from Julia source
+
+ The same as ``IOContext(io::IO, KV::Pair)``\ , but accepting properties as keyword arguments.
 
 Text I/O
 --------
@@ -717,6 +729,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``\ .