Skip to content
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

Update MIME docstring #56942

Open
wants to merge 6 commits into
base: master
Choose a base branch
from

Conversation

nathanrboyer
Copy link
Contributor

Closes #56768

@nsajko nsajko added docs This change adds or pertains to documentation display and printing Aesthetics and correctness of printed representations of objects. labels Jan 3, 2025
@giordano giordano requested a review from stevengj January 4, 2025 02:15
A type representing a standard internet data format. "MIME" stands for
"Multipurpose Internet Mail Extensions", since the standard was originally
used to describe multimedia attachments to email messages.
A parametric type representing a standard internet data format.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A parametric type representing a standard internet data format.
A parametric type representing a content type/format, which is used to define [`show`](@ref)
methods to output objects in different formats and allows [`display(x)`](@ref) to detect
which formats are available for a given `x` in a particular display environment.

Comment on lines +27 to +28
There are over one thousand official media types,
but in practice only a few are usually supported.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
There are over one thousand official media types,
but in practice only a few are usually supported.
There are over one thousand official media types, along with innumerable unofficial application-specific
types (though in practice only a few are usually supported in any given `display` environment).

There are over one thousand official media types,
but in practice only a few are usually supported.
Some common MIMEs are `"text/plain"``, `"text/html"``, `"image/jpeg"``, `"video/mpeg"``.
Unofficial custom MIMEs are also supported.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Unofficial custom MIMEs are also supported.

It's not clear what is meant by "supported" here.

Each media type is defined as a string in the form `"<type>/<subtype>"`.
There are over one thousand official media types,
but in practice only a few are usually supported.
Some common MIMEs are `"text/plain"``, `"text/html"``, `"image/jpeg"``, `"video/mpeg"``.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Some common MIMEs are `"text/plain"``, `"text/html"``, `"image/jpeg"``, `"video/mpeg"``.
Examples of common media types include `"text/plain"``, `"text/html"``, `"image/jpeg"``, `"video/mpeg"``.

Comment on lines +34 to +35
[`@MIME_str`](@ref) is defined to simplify creation of singleton types in this way,
e.g. `MIME"text/plain"`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
[`@MIME_str`](@ref) is defined to simplify creation of singleton types in this way,
e.g. `MIME"text/plain"`.
The string macro [`@MIME_str`](@ref) allow you to specify `MIME{Symbol("...")}` types more succinctly
as `MIME"..."`, for example `MIME"text/plain"`.

e.g. `MIME"text/plain"`.
Singleton MIME types can be used to add new methods to the [`show`](@ref) function.

A `MIME` **object** is created by calling the MIME constructor, either directly,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A `MIME` **object** is created by calling the MIME constructor, either directly,
A `MIME` **instance** is created by calling the MIME constructor, either directly,

Comment on lines +40 to +41
A `MIME` object can be passed as the second argument to [`show`](@ref)
to request output in that format.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A `MIME` object can be passed as the second argument to [`show`](@ref)
to request output in that format.
A `mime::MIME` instance can be passed as the second argument to [`show(io, mime, x)`](@ref)
to request output in that format (if it is implemented for `x`), as well as to various other functions like
[`showable`](@ref), [`repr`](@ref), and [`display`](@ref); most such functions also allow you to
pass a string (e.g. `"text/plain"`) that will be converted to a `MIME` instance for you.

Comment on lines +54 to +56
julia> import Base.show

julia> show(io::IO, ::MIME"text/plain", x::MyType) = print(io, "My Value is ", x.val);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
julia> import Base.show
julia> show(io::IO, ::MIME"text/plain", x::MyType) = print(io, "My Value is ", x.val);
julia> Base.show(io::IO, ::MIME"text/plain", x::MyType) = print(io, "My Value is ", x.val);

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
display and printing Aesthetics and correctness of printed representations of objects. docs This change adds or pertains to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Docs information on MIMEs?
3 participants