Move many IO docstrings inline, cleanup (#19405)

Move many IO docstrings inline, cleanup

Author: kshyatt

base/datafmt.jl

@@ -16,6 +16,14 @@ invalid_dlm(::Type{UInt32}) = 0xfffffffe
 const offs_chunk_size = 5000
 
 countlines(f::AbstractString, eol::Char='\n') = open(io->countlines(io,eol), f)::Int
+
+"""
+    countlines(io::IO, eol::Char='\\n')
+
+Read `io` until the end of the stream/file and count the number of lines. To specify a file
+pass the filename as the first argument. EOL markers other than `'\\n'` are supported by
+passing them as the second argument.
+"""
 function countlines(io::IO, eol::Char='\n')
     isascii(eol) || throw(ArgumentError("only ASCII line terminators are supported"))
     aeol = UInt8(eol)

base/docs/helpdb/Base.jl

@@ -764,13 +764,6 @@ Sum elements of `A` over the singleton dimensions of `r`, and write results to `
 """
 sum!
 
-"""
-    parentindexes(A)
-
-From an array view `A`, returns the corresponding indexes in the parent.
-"""
-parentindexes
-
 """
     display(x)
     display(d::Display, x)
@@ -851,16 +844,6 @@ julia> num2hex(2.2)
 """
 num2hex
 
-"""
-    displayable(mime) -> Bool
-    displayable(d::Display, mime) -> Bool
-
-Returns a boolean value indicating whether the given `mime` type (string) is displayable by
-any of the displays in the current display stack, or specifically by the display `d` in the
-second variant.
-"""
-displayable
-
 """
     truncate(file,n)
 
@@ -924,24 +907,6 @@ creating a new stream.
 """
 accept
 
-"""
-    readstring(stream::IO)
-    readstring(filename::AbstractString)
-
-Read the entire contents of an I/O stream or a file as a string.
-The text is assumed to be encoded in UTF-8.
-"""
-readstring
-
-"""
-    eachline(stream::IO)
-    eachline(filename::AbstractString)
-
-Create an iterable object that will yield each line from an I/O stream or a file.
-The text is assumed to be encoded in UTF-8.
-"""
-eachline
-
 """
     Mmap.Anonymous(name, readonly, create)
 
@@ -1704,16 +1669,6 @@ julia> minimum(A, 2)
 """
 minimum(A,dims)
 
-"""
-    view(A, inds...)
-
-Like [`getindex`](:func:`getindex`), but returns a view into the parent array `A` with the
-given indices instead of making a copy.  Calling [`getindex`](:func:`getindex`) or
-[`setindex!`](:func:`setindex!`) on the returned [`SubArray`](:obj:`SubArray`) computes the
-indices to the parent array on the fly without checking bounds.
-"""
-view
-
 """
     cot(x)
 
@@ -2358,15 +2313,6 @@ Assign `x` to a named field in `value` of composite type. The syntax `a.b = c` c
 """
 setfield!
 
-"""
-    countlines(io,[eol::Char])
-
-Read `io` until the end of the stream/file and count the number of lines. To specify a file
-pass the filename as the first argument. EOL markers other than '\\n' are supported by
-passing them as the second argument.
-"""
-countlines
-
 """
     .\\(x, y)
 
@@ -2429,15 +2375,6 @@ Get the system time in seconds since the epoch, with fairly high (typically, mic
 """
 time()
 
-"""
-    TextDisplay(stream)
-
-Returns a `TextDisplay <: Display`, which can display any object as the text/plain MIME type
-(only), writing the text representation to the given I/O stream. (The text representation is
-the same as the way an object is printed in the Julia REPL.)
-"""
-TextDisplay
-
 """
     ismatch(r::Regex, s::AbstractString) -> Bool
 
@@ -2676,15 +2613,6 @@ Similar to [`show`](:func:`show`), except shows all elements of arrays.
 """
 showall
 
-"""
-    mimewritable(mime, x)
-
-Returns a boolean value indicating whether or not the object `x` can be written as the given
-`mime` type. (By default, this is determined automatically by the existence of the
-corresponding [`show`](:func:`show`) function for `typeof(x)`.)
-"""
-mimewritable
-
 """
     match(r::Regex, s::AbstractString[, idx::Integer[, addopts]])
 

base/io.jl

@@ -156,7 +156,6 @@ Open a file and read its contents. `args` is passed to `read`: this is equivalen
 """
 read(filename::AbstractString, args...) = open(io->read(io, args...), filename)
 read!(filename::AbstractString, a) = open(io->read!(io, a), filename)
-readstring(filename::AbstractString) = open(readstring, filename)
 
 """
     readuntil(stream::IO, delim)
@@ -499,7 +498,15 @@ function read(s::IO, nb=typemax(Int))
     return resize!(b, nr)
 end
 
+"""
+    readstring(stream::IO)
+    readstring(filename::AbstractString)
+
+Read the entire contents of an I/O stream or a file as a string.
+The text is assumed to be encoded in UTF-8.
+"""
 readstring(s::IO) = String(read(s))
+readstring(filename::AbstractString) = open(readstring, filename)
 
 ## high-level iterator interfaces ##
 
@@ -509,6 +516,14 @@ type EachLine
     EachLine(stream) = EachLine(stream, ()->nothing)
     EachLine(stream, ondone) = new(stream, ondone)
 end
+
+"""
+    eachline(stream::IO)
+    eachline(filename::AbstractString)
+
+Create an iterable object that will yield each line from an I/O stream or a file.
+The text is assumed to be encoded in UTF-8.
+"""
 eachline(stream::IO) = EachLine(stream)
 function eachline(filename::AbstractString)
     s = open(filename)

base/multimedia.jl

@@ -26,6 +26,13 @@ end
 # For any type T one can define show(io, ::MIME"type", x::T) = ...
 # in order to provide a way to export T as a given mime type.
 
+"""
+    mimewritable(mime, x)
+
+Returns a boolean value indicating whether or not the object `x` can be written as the given
+`mime` type. (By default, this is determined automatically by the existence of the
+corresponding [`show`](:func:`show`) method for `typeof(x)`.)
+"""
 mimewritable{mime}(::MIME{mime}, x) =
   method_exists(show, Tuple{IO, MIME{mime}, typeof(x)})
 
@@ -118,10 +125,27 @@ abstract Display
 # it is convenient to accept strings instead of ::MIME
 display(d::Display, mime::AbstractString, x) = display(d, MIME(mime), x)
 display(mime::AbstractString, x) = display(MIME(mime), x)
+
+"""
+    displayable(mime) -> Bool
+    displayable(d::Display, mime) -> Bool
+
+Returns a boolean value indicating whether the given `mime` type (string) is displayable by
+any of the displays in the current display stack, or specifically by the display `d` in the
+second variant.
+"""
 displayable(d::Display, mime::AbstractString) = displayable(d, MIME(mime))
 displayable(mime::AbstractString) = displayable(MIME(mime))
 
 # simplest display, which only knows how to display text/plain
+
+"""
+    TextDisplay(io::IO)
+
+Returns a `TextDisplay <: Display`, which can display any object as the text/plain MIME type
+(only), writing the text representation to the given I/O stream. (The text representation is
+the same as the way an object is printed in the Julia REPL.)
+"""
 immutable TextDisplay <: Display
     io::IO
 end

base/subarray.jl

@@ -58,6 +58,11 @@ parent(V::SubArray) = V.parent
 parentindexes(V::SubArray) = V.indexes
 
 parent(a::AbstractArray) = a
+"""
+    parentindexes(A)
+
+From an array view `A`, returns the corresponding indexes in the parent.
+"""
 parentindexes(a::AbstractArray) = ntuple(i->OneTo(size(a,i)), ndims(a))
 
 ## SubArray creation
@@ -68,6 +73,14 @@ parentindexes(a::AbstractArray) = ntuple(i->OneTo(size(a,i)), ndims(a))
 _maybe_reshape_parent(A::AbstractArray, ::NTuple{1, Bool}) = reshape(A, Val{1})
 _maybe_reshape_parent{_,N}(A::AbstractArray{_,N}, ::NTuple{N, Bool}) = A
 _maybe_reshape_parent{N}(A::AbstractArray, ::NTuple{N, Bool}) = reshape(A, Val{N}) # TODO: DEPRECATE FOR #14770
+"""
+    view(A, inds...)
+
+Like [`getindex`](:func:`getindex`), but returns a view into the parent array `A` with the
+given indices instead of making a copy.  Calling [`getindex`](:func:`getindex`) or
+[`setindex!`](:func:`setindex!`) on the returned [`SubArray`](:obj:`SubArray`) computes the
+indices to the parent array on the fly without checking bounds.
+"""
 function view(A::AbstractArray, I::ViewIndex...)
     @_inline_meta
     @boundscheck checkbounds(A, I...)

doc/stdlib/io-network.rst

@@ -398,11 +398,11 @@ General I/O
 
    Advance the stream until before the first character for which ``predicate`` returns ``false``\ . For example ``skipchars(stream, isspace)`` will skip all whitespace. If keyword argument ``linecomment`` is specified, characters from that character through the end of a line will also be skipped.
 
-.. function:: countlines(io,[eol::Char])
+.. function:: countlines(io::IO, eol::Char='\\n')
 
    .. Docstring generated from Julia source
 
-   Read ``io`` until the end of the stream/file and count the number of lines. To specify a file pass the filename as the first argument. EOL markers other than '\\n' are supported by passing them as the second argument.
+   Read ``io`` until the end of the stream/file and count the number of lines. To specify a file pass the filename as the first argument. EOL markers other than ``'\n'`` are supported by passing them as the second argument.
 
 .. function:: PipeBuffer(data::Vector{UInt8}=UInt8[],[maxsize::Int=typemax(Int)])
 
@@ -780,7 +780,7 @@ Julia environments (such as the IPython-based IJulia notebook).
 
    .. Docstring generated from Julia source
 
-   Returns a boolean value indicating whether or not the object ``x`` can be written as the given ``mime`` type. (By default, this is determined automatically by the existence of the corresponding :func:`show` function for ``typeof(x)``\ .)
+   Returns a boolean value indicating whether or not the object ``x`` can be written as the given ``mime`` type. (By default, this is determined automatically by the existence of the corresponding :func:`show` method for ``typeof(x)``\ .)
 
 .. function:: reprmime(mime, x)
 
@@ -835,7 +835,7 @@ stack with:
 
    Pop the topmost backend off of the display-backend stack, or the topmost copy of ``d`` in the second variant.
 
-.. function:: TextDisplay(stream)
+.. function:: TextDisplay(io::IO)
 
    .. Docstring generated from Julia source