From 8ff738e0c2313b2a8be80ace07b87ed858638d2a Mon Sep 17 00:00:00 2001
From: kshyatt <kshyatt@physics.ucsb.edu>
Date: Sat, 24 Jun 2017 17:14:57 -0700
Subject: [PATCH] I love # Example

Ref #22522
(cherry picked from commit 9c6466afd50c5ffa5ae1fa8ee5e9fd4ecb1749c1)
---
 base/iterators.jl     | 20 +++++++++++++++++++-
 base/strings/basic.jl | 30 ++++++++++++++++++++++++++++++
 2 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/base/iterators.jl b/base/iterators.jl
index 1c2ab13f8e113..ef4e7acf66f66 100644
--- a/base/iterators.jl
+++ b/base/iterators.jl
@@ -43,6 +43,8 @@ for indexing `iter`; it's also possible that `x != iter[i]`, if `iter`
 has indices that do not start at 1. See the `enumerate(IndexLinear(),
 iter)` method if you want to ensure that `i` is an index.
 
+# Example
+
 ```jldoctest
 julia> a = ["a", "b", "c"];
 
@@ -90,6 +92,8 @@ specifying `IndexCartesian()` ensures that `i` will be a
 `CartesianIndex`; specifying `IndexStyle(A)` chooses whichever has
 been defined as the native indexing style for array `A`.
 
+# Examples
+
 ```jldoctest
 julia> A = ["a" "d"; "b" "e"; "c" "f"];
 
@@ -202,6 +206,8 @@ the `i`th component of each input iterable.
 
 Note that [`zip`](@ref) is its own inverse: `collect(zip(zip(a...)...)) == collect(a)`.
 
+# Example
+
 ```jldoctest
 julia> a = 1:5
 1:5
@@ -357,6 +363,8 @@ end
 
 An iterator that generates at most the first `n` elements of `iter`.
 
+# Example
+
 ```jldoctest
 julia> a = 1:2:11
 1:2:11
@@ -412,6 +420,8 @@ end
 
 An iterator that generates all but the first `n` elements of `iter`.
 
+# Example
+
 ```jldoctest
 julia> a = 1:2:11
 1:2:11
@@ -505,6 +515,8 @@ repeated(x) = Repeated(x)
 An iterator that generates the value `x` forever. If `n` is specified, generates `x` that
 many times (equivalent to `take(repeated(x), n)`).
 
+# Example
+
 ```jldoctest
 julia> a = Iterators.repeated([1 2], 4);
 
@@ -594,6 +606,8 @@ Returns an iterator over the product of several iterators. Each generated elemen
 a tuple whose `i`th element comes from the `i`th argument iterator. The first iterator
 changes the fastest. Example:
 
+# Example
+
 ```jldoctest
 julia> collect(Iterators.product(1:2,3:5))
 2×3 Array{Tuple{Int64,Int64},2}:
@@ -669,7 +683,9 @@ end
 
 Given an iterator that yields iterators, return an iterator that yields the
 elements of those iterators.
-Put differently, the elements of the argument iterator are concatenated. Example:
+Put differently, the elements of the argument iterator are concatenated.
+
+# Example
 
 ```jldoctest
 julia> collect(Iterators.flatten((1:2, 8:9)))
@@ -724,6 +740,8 @@ end
 
 Iterate over a collection `n` elements at a time.
 
+# Example
+
 ```jldoctest
 julia> collect(Iterators.partition([1,2,3,4,5], 2))
 3-element Array{Array{Int64,1},1}:
diff --git a/base/strings/basic.jl b/base/strings/basic.jl
index df3e4bdf6db81..d46e490e50e84 100644
--- a/base/strings/basic.jl
+++ b/base/strings/basic.jl
@@ -46,6 +46,8 @@ Symbol(s::AbstractString) = Symbol(String(s))
 
 The number of bytes in string `s`.
 
+# Example
+
 ```jldoctest
 julia> sizeof("❤")
 3
@@ -62,6 +64,8 @@ eltype(::Type{<:AbstractString}) = Char
 
 Concatenate strings. The `*` operator is an alias to this function.
 
+# Example
+
 ```jldoctest
 julia> "Hello " * "world"
 "Hello world"
@@ -78,6 +82,8 @@ length(s::DirectIndexString) = endof(s)
 
 The number of characters in string `s`.
 
+# Example
+
 ```jldoctest
 julia> length("jμΛIα")
 5
@@ -138,6 +144,8 @@ isvalid(s::DirectIndexString, i::Integer) = (start(s) <= i <= endof(s))
 
 Tells whether index `i` is valid for the given string.
 
+# Examples
+
 ```jldoctest
 julia> str = "αβγdef";
 
@@ -179,6 +187,8 @@ nextind(s::AbstractArray    , i::Integer) = Int(i)+1
 Get the previous valid string index before `i`.
 Returns a value less than `1` at the beginning of the string.
 
+# Examples
+
 ```jldoctest
 julia> prevind("αβγdef", 3)
 1
@@ -208,6 +218,8 @@ end
 Get the next valid string index after `i`.
 Returns a value greater than `endof(str)` at or after the end of the string.
 
+# Examples
+
 ```jldoctest
 julia> str = "αβγdef";
 
@@ -255,6 +267,8 @@ respect to string `s`.
 
 See also [`chr2ind`](@ref).
 
+# Example
+
 ```jldoctest
 julia> str = "αβγdef";
 
@@ -286,6 +300,8 @@ Convert a character index `i` to a byte index.
 
 See also [`ind2chr`](@ref).
 
+# Example
+
 ```jldoctest
 julia> str = "αβγdef";
 
@@ -328,6 +344,8 @@ eltype(::Type{EachStringIndex}) = Int
 
 Gives the number of columns needed to print a string.
 
+# Example
+
 ```jldoctest
 julia> strwidth("March")
 5
@@ -354,6 +372,8 @@ promote_rule(::Type{<:AbstractString}, ::Type{<:AbstractString}) = String
 Tests whether a character is a valid hexadecimal digit. Note that this does not
 include `x` (as in the standard `0x` prefix).
 
+# Example
+
 ```jldoctest
 julia> isxdigit('a')
 true
@@ -371,6 +391,8 @@ isxdigit(c::Char) = '0'<=c<='9' || 'a'<=c<='f' || 'A'<=c<='F'
 
 Returns `s` with all characters converted to uppercase.
 
+# Example
+
 ```jldoctest
 julia> uppercase("Julia")
 "JULIA"
@@ -383,6 +405,8 @@ uppercase(s::AbstractString) = map(uppercase, s)
 
 Returns `s` with all characters converted to lowercase.
 
+# Example
+
 ```jldoctest
 julia> lowercase("STRINGS AND THINGS")
 "strings and things"
@@ -395,6 +419,8 @@ lowercase(s::AbstractString) = map(lowercase, s)
 
 Capitalizes the first character of each word in `s`.
 
+# Example
+
 ```jldoctest
 julia> titlecase("the julia programming language")
 "The Julia Programming Language"
@@ -420,6 +446,8 @@ end
 
 Returns `string` with the first character converted to uppercase.
 
+# Example
+
 ```jldoctest
 julia> ucfirst("python")
 "Python"
@@ -434,6 +462,8 @@ end
 
 Returns `string` with the first character converted to lowercase.
 
+# Example
+
 ```jldoctest
 julia> lcfirst("Julia")
 "julia"