From 147d5b101cea8c845b81c80943a8089bd59f5e1a Mon Sep 17 00:00:00 2001
From: Jeff Bezanson <jeff.bezanson@gmail.com>
Date: Mon, 1 Jun 2020 14:58:40 -0400
Subject: [PATCH] clarify `show` doc strings (#36076)

fixes #36072
---
 base/multimedia.jl         | 18 ++++++++++--------
 base/show.jl               | 23 +++++++++++++++--------
 doc/src/base/io-network.md |  4 ++--
 3 files changed, 27 insertions(+), 18 deletions(-)

diff --git a/base/multimedia.jl b/base/multimedia.jl
index a50ea4690c994..4729849cfbc8d 100644
--- a/base/multimedia.jl
+++ b/base/multimedia.jl
@@ -77,7 +77,7 @@ showable(::MIME{mime}, @nospecialize x) where {mime} = hasmethod(show, Tuple{IO,
 showable(m::AbstractString, @nospecialize x) = showable(MIME(m), x)
 
 """
-    show(io, mime, x)
+    show(io::IO, mime, x)
 
 The [`display`](@ref) functions ultimately call `show` in order to write an object `x` as a
 given `mime` type to a given I/O stream `io` (usually a memory buffer), if possible. In order
@@ -94,18 +94,20 @@ your images to be displayed on any PNG-capable `AbstractDisplay` (such as IJulia
 to `import Base.show` in order to add new methods to the built-in Julia function
 `show`.
 
-The default MIME type is `MIME"text/plain"`. There is a fallback definition for `text/plain`
-output that calls `show` with 2 arguments. Therefore, this case should be handled by
-defining a 2-argument `show(io::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`](@ref) specifying output format properties.
-See [`IOContext`](@ref) for details.
+The default MIME type is `MIME"text/plain"`. There is a fallback definition for `text/plain`
+output that calls `show` with 2 arguments, so it is not always necessary to add a method
+for that case. If a type benefits from custom human-readable output though,
+`show(::IO, ::MIME"text/plain", ::T)` should be defined. For example, the `Day` type uses
+`1 day` as the output for the `text/plain` MIME type, and `Day(1)` as the output of 2-argument `show`.
+
+Container types generally implement 3-argument `show` by calling `show(io, MIME"text/plain"(), x)`
+for elements `x`, with `:compact => true` set in an [`IOContext`](@ref) passed as the first argument.
 """
-show(stream, mime, x)
+show(stream::IO, mime, x)
 show(io::IO, m::AbstractString, x) = show(io, MIME(m), x)
 
 """
diff --git a/base/show.jl b/base/show.jl
index 17aa231a2b5c3..c361fb4dd88b9 100644
--- a/base/show.jl
+++ b/base/show.jl
@@ -265,9 +265,9 @@ the properties of that stream (note that `io` can itself be an `IOContext`).
 
 The following properties are in common use:
 
- - `:compact`: Boolean specifying that small values should be printed more compactly, e.g.
+ - `:compact`: Boolean specifying that values should be printed more compactly, e.g.
    that numbers should be printed with fewer digits. This is set when printing array
-   elements.
+   elements. `:compact` output should not contain line breaks.
  - `: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
@@ -358,14 +358,21 @@ function show_circular(io::IOContext, @nospecialize(x))
 end
 
 """
-    show(x)
+    show([io::IO = stdout], x)
 
-Write an informative text representation of a value to the current output stream. New types
-should overload `show(io::IO, x)` where the first argument is a stream. The representation used
-by `show` generally includes Julia-specific formatting and type information.
+Write a text representation of a value `x` to the output stream `io`. New types `T`
+should overload `show(io::IO, x::T)`. The representation used by `show` generally
+includes Julia-specific formatting and type information, and should be parseable
+Julia code when possible.
 
 [`repr`](@ref) returns the output of `show` as a string.
 
+To customize human-readable text output for objects of type `T`, define
+`show(io::IO, ::MIME"text/plain", ::T)` instead. Checking the `:compact`
+[`IOContext`](@ref) property of `io` in such methods is recommended,
+since some containers show their elements by calling this method with
+`:compact => true`.
+
 See also [`print`](@ref), which writes un-decorated representations.
 
 # Examples
@@ -376,10 +383,10 @@ julia> print("Hello World!")
 Hello World!
 ```
 """
-show(x) = show(stdout::IO, x)
-
 show(io::IO, @nospecialize(x)) = show_default(io, x)
 
+show(x) = show(stdout::IO, x)
+
 # avoid inferring show_default on the type of `x`
 show_default(io::IO, @nospecialize(x)) = _show_default(io, inferencebarrier(x))
 
diff --git a/doc/src/base/io-network.md b/doc/src/base/io-network.md
index adaa8e8b53856..101cdc890f9a9 100644
--- a/doc/src/base/io-network.md
+++ b/doc/src/base/io-network.md
@@ -55,7 +55,7 @@ Base.IOContext(::IO, ::IOContext)
 ## Text I/O
 
 ```@docs
-Base.show(::Any)
+Base.show(::IO, ::Any)
 Base.summary
 Base.print
 Base.println
@@ -93,7 +93,7 @@ Base.AbstractDisplay
 Base.Multimedia.display
 Base.Multimedia.redisplay
 Base.Multimedia.displayable
-Base.show(::Any, ::Any, ::Any)
+Base.show(::IO, ::Any, ::Any)
 Base.Multimedia.showable
 Base.repr(::MIME, ::Any)
 Base.MIME