New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

IOContext docstrings would benefit from more examples #22637

Closed
Sacha0 opened this Issue Jun 30, 2017 · 0 comments

Comments

Projects
None yet
2 participants
@Sacha0
Member

Sacha0 commented Jun 30, 2017

The existing docstrings for IOContext (copied below) together contain only one example, and that example references a property not mentioned elsewhere in those docstrings. An example or two for each signature would make these methods much easier to grasp. Best!

IOContext

  IOContext provides a mechanism for passing output configuration settings among show
  methods.

  In short, it is an immutable dictionary that is a subclass of IO. It supports standard
  dictionary operations such as getindex, and can also be used as an I/O stream.

  IOContext(io::IO; properties...)

  The same as IOContext(io::IO, KV::Pair), but accepting properties as keyword arguments.

  IOContext(io::IO, context::IOContext)

  Create an IOContext that wraps an alternate IO but inherits the properties of context.

  IOContext(io::IO, KV::Pair)

  Create an IOContext that wraps a given stream, adding the specified key=>value pair to the
  properties of that stream (note that io can itself be an IOContext).

    •    use (key => value) in dict to see if this particular combination is in the
        properties set

    •    use get(dict, key, default) to retrieve the most recent value for a particular
        key


  The following properties are in common use::compact: Boolean specifying that small values should be printed more compactly,
        e.g. that numbers should be printed with fewer digits. This is set when printing
        array elements.

    •    :limit: Boolean specifying that containers should be truncated, e.g. showing …
        in place of most elements.

    •    :displaysize: A Tuple{Int,Int} giving the size in rows and columns to use for
        text output. This can be used to override the display size for called functions,
        but to get the size of the screen use the displaysize function.


  julia> function f(io::IO)
             if get(io, :short, false)
                 print(io, "short")
             else
                 print(io, "loooooong")
             end
         end
  f (generic function with 1 method)

  julia> f(STDOUT)
  loooooong
  julia> f(IOContext(STDOUT, :short => true))
  short
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment