fixes some documentation issues spotted by @timholy

Author: ssfrr

README.md

@@ -168,8 +168,9 @@ end
 Note that these are `load` and `save`, **not** `FileIO.load` and `FileIO.save`.
 Because a given format might have multiple packages that are capable of reading it,
 FileIO will dispatch to these using module-scoping, e.g., `SomePkg.load(args...)`.
-Consequently, **packages should define "private" `load` and `save` methods, and 
-not extend (import) FileIO's**. 
+Consequently, **packages should define "private" `load` and `save` methods (also
+`loadstreaming` and `savestreaming` if you implement them), and not extend
+(import) FileIO's**.
 
 `load(::File)` and `save(::File)` should close any streams
 they open.  (If you use the `do` syntax, this happens for you
@@ -191,17 +192,19 @@ struct WAVReader
     ownstream::Bool
 end
 
-function read(reader::WAVReader, frames::Int)
+function Base.read(reader::WAVReader, frames::Int)
     # read and decode audio samples from reader.io
 end
 
-function close(reader::WAVReader)
+function Base.close(reader::WAVReader)
     # do whatever cleanup the reader needs
     reader.ownstream && close(reader.io)
 end
+
+# FileIO has fallback functions that make these work using `do` syntax as well,
+# and will automatically call `close` on the returned object.
 loadstreaming(f::File{format"WAV"}) = WAVReader(open(f), true)
 loadstreaming(s::Stream{format"WAV"}) = WAVReader(s, false)
-# FileIO has fallback functions that make these work using `do` syntax as well.
 ```
 
 If you choose to implement `loadstreaming` and `savestreaming` in your package,
@@ -215,7 +218,7 @@ function save(q::Formatted{format"WAV"}, data, args...; kwargs...)
 end
 
 function load(q::Formatted{format"WAV"}, args...; kwargs...)
-    savestreaming(q, args...; kwargs...) do stream
+    loadstreaming(q, args...; kwargs...) do stream
         read(stream)
     end
 end

src/loadsave.jl

@@ -44,8 +44,10 @@ add_saver
 - `load(filename)` loads the contents of a formatted file, trying to infer
 the format from `filename` and/or magic bytes in the file.
 - `load(strm)` loads from an `IOStream` or similar object. In this case,
-the magic bytes are essential.
-- `load(File(format"PNG",filename))` specifies the format directly, and bypasses inference.
+there is no filename extension, so we rely on the magic bytes for format
+identification.
+- `load(File(format"PNG", filename))` specifies the format directly, and bypasses inference.
+- `load(Stream(format"PNG", io))` specifies the format directly, and bypasses inference.
 - `load(f; options...)` passes keyword arguments on to the loader.
 """
 load
@@ -60,17 +62,22 @@ video or audio.
 the format from `filename` and/or magic bytes in the file. It returns a streaming
 type that can be read from in chunks, rather than loading the whole contents all
 at once
-- `loadstreaming(strm)` loads the stream from an `IOStream` or similar object. In this case,
-the magic bytes are essential.
-- `load(File(format"PNG",filename))` specifies the format directly, and bypasses inference.
-- `load(f; options...)` passes keyword arguments on to the loader.
+- `loadstreaming(strm)` loads the stream from an `IOStream` or similar object.
+In this case, there is no filename extension, so we rely on the magic bytes
+for format identification.
+- `loadstreaming(File(format"WAV",filename))` specifies the format directly, and
+bypasses inference.
+- `loadstreaming(Stream(format"WAV", io))` specifies the format directly, and
+bypasses inference.
+- `loadstreaming(f; options...)` passes keyword arguments on to the loader.
 """
 loadstreaming
 
 """
 - `save(filename, data...)` saves the contents of a formatted file,
 trying to infer the format from `filename`.
 - `save(Stream(format"PNG",io), data...)` specifies the format directly, and bypasses inference.
+- `save(File(format"PNG",filename), data...)` specifies the format directly, and bypasses inference.
 - `save(f, data...; options...)` passes keyword arguments on to the saver.
 """
 save
@@ -82,7 +89,10 @@ accept formatted objects, like an image or chunk of video or audio.
 
 - `savestreaming(filename, data...)` saves the contents of a formatted file,
 trying to infer the format from `filename`.
-- `savestreaming(Stream(format"PNG",io), data...)` specifies the format directly, and bypasses inference.
+- `savestreaming(File(format"WAV",filename))` specifies the format directly, and
+bypasses inference.
+- `savestreaming(Stream(format"WAV", io))` specifies the format directly, and
+bypasses inference.
 - `savestreaming(f, data...; options...)` passes keyword arguments on to the saver.
 """
 savestreaming