add more explanation to doc strings for show, print, string, repr (#3…

…0918)

fixes #21982

base/show.jl

@@ -307,8 +307,20 @@ end
     show(x)
 
 Write an informative text representation of a value to the current output stream. New types
-should overload `show(io, x)` where the first argument is a stream. The representation used
+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.
+
+[`repr`](@ref) returns the output of `show` as a string.
+
+See also [`print`](@ref), which writes un-decorated representations.
+
+# Examples
+```jldoctest
+julia> show("Hello World!")
+"Hello World!"
+julia> print("Hello World!")
+Hello World!
+```
 """
 show(x) = show(stdout::IO, x)
 

base/strings/io.jl

@@ -6,13 +6,19 @@
     print([io::IO], xs...)
 
 Write to `io` (or to the default output stream [`stdout`](@ref)
-if `io` is not given) a canonical (un-decorated) text representation
-of values `xs` if there is one, otherwise call [`show`](@ref).
+if `io` is not given) a canonical (un-decorated) text representation.
 The representation used by `print` includes minimal formatting and tries to
 avoid Julia-specific details.
 
 Printing `nothing` is not allowed and throws an error.
 
+`print` falls back to calling `show`, so most types should just define
+`show`. Define `print` if your type has a separate "plain" representation.
+For example, `show` displays strings with quotes, and `print` displays strings
+without quotes.
+
+[`string`](@ref) returns the output of `print` as a string.
+
 # Examples
 ```jldoctest
 julia> print("Hello World!")
@@ -147,6 +153,12 @@ end
 
 Create a string from any values, except `nothing`, using the [`print`](@ref) function.
 
+`string` should usually not be defined directly. Instead, define a method
+`print(io::IO, x::MyType)`. If `string(x)` for a certain type needs to be
+highly efficient, then it may make sense to add a method to `string` and
+define `print(io::IO, x::MyType) = print(io, string(x))` to ensure the
+functions are consistent.
+
 # Examples
 ```jldoctest
 julia> string("a", 1, true)
@@ -180,6 +192,7 @@ end
     repr(x; context=nothing)
 
 Create a string from any value using the [`show`](@ref) function.
+You should not add methods to `repr`; define a `show` method instead.
 
 The optional keyword argument `context` can be set to an `IO` or [`IOContext`](@ref)
 object whose attributes are used for the I/O stream passed to `show`.

doc/src/manual/strings.md

@@ -507,7 +507,7 @@ julia> "$greet, $whom.\n"
 ```
 
 This is more readable and convenient and equivalent to the above string concatenation -- the system
-rewrites this apparent single string literal into a concatenation of string literals with variables.
+rewrites this apparent single string literal into the call `string(greet, ", ", whom, ".\n")`.
 
 The shortest complete expression after the `$` is taken as the expression whose value is to be
 interpolated into the string. Thus, you can interpolate any expression into a string using parentheses:
@@ -518,7 +518,10 @@ julia> "1 + 2 = $(1 + 2)"
 ```
 
 Both concatenation and string interpolation call [`string`](@ref) to convert objects into string
-form. Most non-`AbstractString` objects are converted to strings closely corresponding to how
+form. However, `string` actually just returns the output of [`print`](@ref), so new types
+should add methods to [`print`](@ref) or [`show`](@ref) instead of `string`.
+
+Most non-`AbstractString` objects are converted to strings closely corresponding to how
 they are entered as literal expressions:
 
 ```jldoctest