From d247ca8ea566265f23258c49b806d6835b060175 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bogumi=C5=82=20Kami=C5=84ski?= <bkamins@sgh.waw.pl>
Date: Sun, 20 May 2018 23:07:31 +0200
Subject: [PATCH] improve sizeof and repr documentation (#26926)

---
 base/essentials.jl    | 14 +++++++++++---
 base/strings/basic.jl | 16 ++++++++++++++++
 base/strings/io.jl    |  8 +++++++-
 3 files changed, 34 insertions(+), 4 deletions(-)

diff --git a/base/essentials.jl b/base/essentials.jl
index 1ed515cdaa0f5..3734c956d0532 100644
--- a/base/essentials.jl
+++ b/base/essentials.jl
@@ -353,9 +353,11 @@ reinterpret(::Type{Unsigned}, x::Float16) = reinterpret(UInt16,x)
 reinterpret(::Type{Signed}, x::Float16) = reinterpret(Int16,x)
 
 """
-    sizeof(T)
+    sizeof(T::DataType)
+    sizeof(obj)
 
-Size, in bytes, of the canonical binary representation of the given DataType `T`, if any.
+Size, in bytes, of the canonical binary representation of the given `DataType` `T`, if any.
+Size, in bytes, of object `obj` if it is not `DataType`.
 
 # Examples
 ```jldoctest
@@ -364,9 +366,15 @@ julia> sizeof(Float32)
 
 julia> sizeof(ComplexF64)
 16
+
+julia> sizeof(1.0)
+8
+
+julia> sizeof([1.0:10.0;])
+80
 ```
 
-If `T` does not have a specific size, an error is thrown.
+If `DataType` `T` does not have a specific size, an error is thrown.
 
 ```jldoctest
 julia> sizeof(AbstractArray)
diff --git a/base/strings/basic.jl b/base/strings/basic.jl
index ae669be14fb8b..1090f490fd32d 100644
--- a/base/strings/basic.jl
+++ b/base/strings/basic.jl
@@ -138,6 +138,22 @@ See also: [`getindex`](@ref), [`checkbounds`](@ref)
 ## basic generic definitions ##
 
 eltype(::Type{<:AbstractString}) = Char # some string types may use another AbstractChar
+
+"""
+    sizeof(str::AbstractString)
+
+Size, in bytes, of the string `s`. Equal to the number of code units in `s` multiplied by
+the size, in bytes, of one code unit in `s`.
+
+# Examples
+```jldoctest
+julia> sizeof("")
+0
+
+julia> sizeof("∀")
+3
+```
+"""
 sizeof(s::AbstractString) = ncodeunits(s) * sizeof(codeunit(s))
 firstindex(s::AbstractString) = 1
 lastindex(s::AbstractString) = thisind(s, ncodeunits(s))
diff --git a/base/strings/io.jl b/base/strings/io.jl
index bccf95004e9f0..4ea265da543f7 100644
--- a/base/strings/io.jl
+++ b/base/strings/io.jl
@@ -170,7 +170,7 @@ The optional keyword argument `context` can be set to an `IO` or [`IOContext`](@
 object whose attributes are used for the I/O stream passed to `show`.
 
 Note that `repr(x)` is usually similar to how the value of `x` would
-be entered in Julia.  See also [`repr("text/plain", x)`](@ref) to instead
+be entered in Julia.  See also [`repr(MIME("text/plain"), x)`](@ref) to instead
 return a "pretty-printed" version of `x` designed more for human consumption,
 equivalent to the REPL display of `x`.
 
@@ -182,6 +182,12 @@ julia> repr(1)
 julia> repr(zeros(3))
 "[0.0, 0.0, 0.0]"
 
+julia> repr(big(1/3))
+"3.33333333333333314829616256247390992939472198486328125e-01"
+
+julia> repr(big(1/3), context=:compact => true)
+"3.33333e-01"
+
 ```
 """
 repr(x; context=nothing) = sprint(show, x; context=context)