From edecee70f5aaeafe16a8b3f77c00b4ac398b07b3 Mon Sep 17 00:00:00 2001
From: kshyatt <kshyatt@physics.ucsb.edu>
Date: Fri, 8 Dec 2017 13:34:26 -0800
Subject: [PATCH] Doctests for reading functions

---
 base/io.jl | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 55 insertions(+), 3 deletions(-)

diff --git a/base/io.jl b/base/io.jl
index 4d7f745b126e5..ad4a1770b3744 100644
--- a/base/io.jl
+++ b/base/io.jl
@@ -250,11 +250,27 @@ read!(filename::AbstractString, a) = open(io->read!(io, a), filename)
 
 Read a string from an I/O stream or a file, up to and including the given delimiter byte.
 The text is assumed to be encoded in UTF-8.
+
+# Examples
+```jldoctest
+julia> open("my_file.txt", "w") do io
+           write(io, "JuliaLang is a GitHub organization.\nIt has many members.\n");
+       end
+57
+
+julia> readuntil("my_file.txt", 'L')
+"JuliaL"
+
+julia> readuntil("my_file.txt", '.')
+"JuliaLang is a GitHub organization."
+
+julia> rm("my_file.txt")
+```
 """
 readuntil(filename::AbstractString, args...) = open(io->readuntil(io, args...), filename)
 
 """
-    readline(stream::IO=STDIN; chomp::Bool=true)
+    readline(io::IO=STDIN; chomp::Bool=true)
     readline(filename::AbstractString; chomp::Bool=true)
 
 Read a single line of text from the given I/O stream or file (defaults to `STDIN`).
@@ -263,6 +279,22 @@ input end with `'\\n'` or `"\\r\\n"` or the end of an input stream. When `chomp`
 true (as it is by default), these trailing newline characters are removed from the
 line before it is returned. When `chomp` is false, they are returned as part of the
 line.
+
+# Examples
+```jldoctest
+julia> open("my_file.txt", "w") do io
+           write(io, "JuliaLang is a GitHub organization.\nIt has many members.\n");
+       end
+57
+
+julia> readline("my_file.txt")
+"JuliaLang is a GitHub organization."
+
+julia> readline("my_file.txt", chomp=false)
+"JuliaLang is a GitHub organization.\n"
+
+julia> rm("my_file.txt")
+```
 """
 function readline(filename::AbstractString; chomp::Bool=true)
     open(filename) do f
@@ -283,12 +315,32 @@ function readline(s::IO=STDIN; chomp::Bool=true)
 end
 
 """
-    readlines(stream::IO=STDIN; chomp::Bool=true)
+    readlines(io::IO=STDIN; chomp::Bool=true)
     readlines(filename::AbstractString; chomp::Bool=true)
 
 Read all lines of an I/O stream or a file as a vector of strings. Behavior is
-equivalent to saving the result of reading `readline` repeatedly with the same
+equivalent to saving the result of reading [`readline`](@ref) repeatedly with the same
 arguments and saving the resulting lines as a vector of strings.
+
+# Examples
+```jldoctest
+julia> open("my_file.txt", "w") do io
+           write(io, "JuliaLang is a GitHub organization.\nIt has many members.\n");
+       end
+57
+
+julia> readlines("my_file.txt")
+2-element Array{String,1}:
+ "JuliaLang is a GitHub organization."
+ "It has many members."
+
+julia> readlines("my_file.txt", chomp=false)
+2-element Array{String,1}:
+ "JuliaLang is a GitHub organization.\n"
+ "It has many members.\n"
+
+julia> rm("my_file.txt")
+```
 """
 function readlines(filename::AbstractString; chomp::Bool=true)
     open(filename) do f