Consistent use of singleton types in manual. #36591

tpapp · 2020-07-09T04:38:28Z

Fixes #7135, see discussion there.

Changes

separate discussion of singleton types (as in Base.issingletontype) and Type{T}
move discussion about singleton types to a later section so that parametric singleton types can be discussed
add example and discussion about parametric singleton types
add usage hint about Type outside dispatch ~~(TL;DR: don't)~~ example: type sharpening (thanks @tkf)

Open questions:

is there a terminology for Type{T} now that we don't confuse it with singleton types? If not, do we want to introduce one, eg call it "type selectors"?
should I mention that abstract types can't be singleton types, or is it obvious from the context?
should I expunge the remaining use of 'singleton' for Type{T} from Conversion and Promotion?

Fixes JuliaLang#7135, see discussion there. - separate discussion of singleton types (as in `Base.issingletontype`) and `Type{T}` - move discussion about singleton types to a later section so that parametric singleton types can be discussed - add example and discussion about parametric singleton types - add usage hint about `Type` outside dispatch (TL;DR: don't)

tkf · 2020-07-09T06:31:09Z

add usage hint about Type outside dispatch (TL;DR: don't)

A usage (workaround) outside dispatch is to get a sharp field type. For example, the type of Fix1(Vector, undef) is Fix1{Type{Vector},UndefInitializer} rather than Fix1{DataType,UndefInitializer}. This is required for the field type to be inferable. So, I think it'd be better to avoid stressing that Type{T} is only for dispatch. "Type{T} types" section in this PR seems to be fine as-is, though.

tkf · 2020-07-09T06:32:03Z

doc/src/manual/types.md

+Immutable composite types with no fields are called *singletons*. Formally, if 
+`a isa T && b isa T` implies `a === b`, then `T` is a singleton type. [^2]


I think the spirit of this formalism is great, but if I have

julia> abstract type A end julia> struct B <: A end

and I don't define any other subtype of A, would it imply that A is also a singleton type?

Maybe making this perfect requires isconcretetype(T)? Although if you say "for any a and b" I guess it could mean "for any a and b of any implementable type."

should I mention that abstract types can't be singleton types, or is it obvious from the context?

So yes, I think this helps to make this definition clearer.

Yes, I think we should stress that only concrete types can to be singletons.

tkf · 2020-07-09T06:35:54Z

is there a terminology for Type{T} now that we don't confuse it with singleton types? If not, do we want to introduce one, eg call it "type selectors"?

Yeah, calling Type{T} a singleton sounds a bit confusing since you can write something like Type{<:Integer}. For the new name, "type selectors" sound reasonable to me.

should I expunge the remaining use of 'singleton' for Type{T} from Conversion and Promotion?

👍 from me :)

tpapp · 2020-07-09T08:13:45Z

@tkf: thanks for the review. Yes, sharp field types are another use case --- if you have a small, self-contained example, I would be happy to add it to the PR if that's OK with you.

I included the usage hint because I have seen users on Discourse trying to work with Type{Type{T}} etc constructs and other misunderstandings. Type is mysterious to a newcomer as is, and each common use case should serve as an example. So I would rather just include them if feasible.

tkf · 2020-07-09T08:36:53Z

Yeah, including example is a good idea. I think a minimal example is Some:

struct SomeBad{T}
    value::T
end

struct SomeGood{T}
    value::T
end
SomeGood(::Type{T}) where {T} = SomeGood{Type{T}}(T)

sbad = SomeBad(Symbol)
sgood = SomeGood(Symbol)

@assert sbad isa SomeBad{DataType}
@assert sgood isa SomeGood{Type{Symbol}}

getvalue(x) = x.value

@code_warntype getvalue(sbad)  # => Body::DataType
@code_warntype getvalue(sgood)  # => Body::Type{Symbol}

@tkf

- remove incorrect reference to "singleton types" from the conversion chapter - emphasize that singleton types need to be concrete types, specifically mention abstract types - include a type sharpening example for `Type{T}` (thanks @tkf) - introduce the term "type selector"

tpapp · 2020-07-09T11:08:46Z

Thanks @tkf, I simplified the example somewhat as I did not want to deal with @code_warntype in a jldoctest. I also did the other changes above.

tpapp · 2020-07-14T14:29:29Z

Friendly bump — if this needs to be improved, I am happy to implement any further suggested changes.

StefanKarpinski · 2020-07-14T18:54:29Z

I've requested review by @JeffBezanson. I'll merge one way or another this week.

rfourquet · 2020-07-16T09:12:01Z

doc/src/manual/conversion-and-promotion.md

@@ -168,13 +168,12 @@ Such a definition might look like this:
 convert(::Type{MyType}, x) = MyType(x)
 ```

-The type of the first argument of this method is a [singleton type](@ref man-singleton-types),
+The type of the first argument of this method is a [`Type{T}`](@ref man-typet-type),
 `Type{MyType}`, the only instance of which is `MyType`. Thus, this method is only invoked


Why not put directly Type{MyType} within the [] brackets, where Type{T} is currently?

doc/src/manual/types.md

rfourquet · 2020-07-16T09:21:02Z

doc/src/manual/types.md

+In other words, [`isa(A,Type{B})`](@ref) is true if and only if `A` and `B` are the same object
+and that object is a type.
+
+In particular, since parametric types are [invariant](@ref man-parametric-composite-types),


Sounds like the sentence is missing a "connection" word, e.g. I would expect "we have:" or something like that at the end, before the example.

doc/src/manual/types.md

Co-authored-by: Rafael Fourquet <[email protected]>

tpapp · 2020-07-16T10:55:15Z

@rfourquet, thanks for the thorough reading and the detailed suggestions, I applied all of them.

StefanKarpinski · 2020-07-16T15:41:08Z

Great clarification. Thank you! This looks ready to merge once CI passes.

doc/src/manual/types.md

rfourquet

Yes nice change! Just one more possible change ("ie" -> "i.e.") if you also update this branch for something else.

rfourquet · 2020-07-17T14:56:30Z

doc/src/manual/types.md

+1. `T` is an immutable composite type (ie defined with `struct`),
+1. `a isa T && b isa T` implies `a === b`,
+
+then `T` is a singleton type.[^2] [`Base.issingletontype`](@ref) can be used to check if a


Is there an official convention on whether the footnote sign should go before or after the period? I saw both in the manual.

The Chicago Manual of Style suggests that it goes after the period.

Incidentally, since these questions are in general important for high-quality documentation, I started some discussion about referring a style guide in #36723.

doc/src/manual/types.md

Co-authored-by: Rafael Fourquet <[email protected]>

tpapp · 2020-07-21T15:07:56Z

Another friendly bump: I think I addressed all comments.

I am happy to wait for more feedback if necessary, just don't want this PR to be forgotten.

tkf · 2020-07-21T20:01:38Z

It has two approvals and the merge me label. I think it's more than enough :)

Fixes JuliaLang#7135, see discussion there. * separate discussion of singleton types (as in `Base.issingletontype`) and `Type{T}` * move discussion about singleton types to a later section so that parametric singleton types can be discussed * add example and discussion about parametric singleton types * add usage hint about `Type` outside dispatch Co-authored-by: Rafael Fourquet <[email protected]> Co-authored-by: Daniel Karrasch <[email protected]>

tkf reviewed Jul 9, 2020

View reviewed changes

StefanKarpinski requested a review from JeffBezanson July 9, 2020 11:41

tkf mentioned this pull request Jul 10, 2020

Fix inference for fix(::Type, ...) goretkin/FixArgs.jl#7

Merged

StefanKarpinski added the status:merge me PR is reviewed. Merge when all tests are passing label Jul 14, 2020

rfourquet reviewed Jul 16, 2020

View reviewed changes

tpapp and others added 4 commits July 16, 2020 12:52

Wording corrections suggested by @rfourquet (thanks!)

8f9049a

remove "the"

b164a1b

Co-authored-by: Rafael Fourquet <[email protected]>

spacing

d3ce71b

Co-authored-by: Rafael Fourquet <[email protected]>

e.g.

d129ce1

Co-authored-by: Rafael Fourquet <[email protected]>

StefanKarpinski approved these changes Jul 16, 2020

View reviewed changes

dkarrasch reviewed Jul 16, 2020

View reviewed changes

doc/src/manual/types.md Outdated Show resolved Hide resolved

fix whitespace

f6f5cf9

rfourquet approved these changes Jul 17, 2020

View reviewed changes

Update doc/src/manual/types.md

428e8c6

Co-authored-by: Rafael Fourquet <[email protected]>

tkf merged commit c6955d7 into JuliaLang:master Jul 21, 2020

goretkin mentioned this pull request Dec 5, 2020

constructors and functions behave differently with respect to isbitstype, sizeof, etc. #38716

Closed

DilumAluthge removed the status:merge me PR is reviewed. Merge when all tests are passing label Jan 11, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Consistent use of singleton types in manual. #36591

Consistent use of singleton types in manual. #36591

tpapp commented Jul 9, 2020 •

edited

Loading

tkf commented Jul 9, 2020

tkf Jul 9, 2020

tpapp Jul 9, 2020

tkf commented Jul 9, 2020

tpapp commented Jul 9, 2020

tkf commented Jul 9, 2020

tpapp commented Jul 9, 2020

tpapp commented Jul 14, 2020

StefanKarpinski commented Jul 14, 2020

rfourquet Jul 16, 2020

rfourquet Jul 16, 2020

tpapp commented Jul 16, 2020

StefanKarpinski commented Jul 16, 2020

rfourquet left a comment

rfourquet Jul 17, 2020

tpapp Jul 18, 2020

tpapp Jul 18, 2020

tpapp commented Jul 21, 2020

tkf commented Jul 21, 2020

		Immutable composite types with no fields are called singletons. Formally, if
		`a isa T && b isa T` implies `a === b`, then `T` is a singleton type. [^2]

Consistent use of singleton types in manual. #36591

Consistent use of singleton types in manual. #36591

Conversation

tpapp commented Jul 9, 2020 • edited Loading

Changes

Open questions:

tkf commented Jul 9, 2020

tkf Jul 9, 2020

Choose a reason for hiding this comment

tpapp Jul 9, 2020

Choose a reason for hiding this comment

tkf commented Jul 9, 2020

tpapp commented Jul 9, 2020

tkf commented Jul 9, 2020

tpapp commented Jul 9, 2020

tpapp commented Jul 14, 2020

StefanKarpinski commented Jul 14, 2020

rfourquet Jul 16, 2020

Choose a reason for hiding this comment

rfourquet Jul 16, 2020

Choose a reason for hiding this comment

tpapp commented Jul 16, 2020

StefanKarpinski commented Jul 16, 2020

rfourquet left a comment

Choose a reason for hiding this comment

rfourquet Jul 17, 2020

Choose a reason for hiding this comment

tpapp Jul 18, 2020

Choose a reason for hiding this comment

tpapp Jul 18, 2020

Choose a reason for hiding this comment

tpapp commented Jul 21, 2020

tkf commented Jul 21, 2020

tpapp commented Jul 9, 2020 •

edited

Loading