Manual could be clearer about parametric singleton types

[david-moon]

I was confused about the meaning of parametric singleton types such as Type{Array{T}}, and the manual section "Singleton Types" does not say anything about them. It should be improved.

The only documentation section I could find that says anything about parametric singleton types is "Case Study: Rational Conversions", which is misleading because it defines methods for convert{T<:Int}(::Type{Rational{T}}, x::...) but not convert(::Type{Rational}, x::...). At first glance it seems like convert(Rational, x) would invoke one of those Type{Rational{T}} methods just as convert(Rational{Int8}, x) would. In fact convert(Rational, x) invokes a method which is not in this documentation section. The convert methods for rational numbers in base/rational.jl are somewhat different from what the documentation says.

Here's a simple example: define f{T}(::Type{Array{T}}) = 1 then f(Array{Int}) invokes that method but f(Array) and f(Array{Int,1}) do not. This makes perfect sense when you think about it, but it isn't really obvious and some specific documentation would help.

BTW unlike the 0.2 version, in the latest version manual on docs.julialang.org the section "Singleton Types" does not show up in the table of contents at all. I am not sure what the problem is. It can be found by going to "Parametric Types" in the table of contents and then scrolling down a long way.

[kshyatt]

Are these docs still unclear? Can we close this?

[tkelman]

No, still open, this doc section has seen essentially no updates since 2013 and it's still a confusing topic: https://github.com/JuliaLang/julia/blame/fdf374875bf6e0a63c182c33d1824ff36605901a/doc/manual/types.rst#L1024

[tpapp]

Also, there are two conceptually related but not fully overlapping uses of "singleton type" in Julia.

The the manual says

For each type T, the "singleton type" Type{T} is an abstract type whose only instance is the object T

while functions in Base.issintletontype and Core.Compiler.singleton_type use this definition:

help?> Base.issingletontype
  Base.issingletontype(T)

  Determine whether type T has exactly one possible instance; for example, a struct type with no fields.

This can be confusing to newcomers who may get the impression that only Types are singleton types.

I propose that

1. we stick to the second definition: a singleton type is a type which has one instance. Formally, T is a singleton type if a isa T and b isa T implies a === b. From this definition, given

   struct Foo{T} end

   Foo{Int} is a singleton type, Foo isn't. This would resolve this issue.

2. explain the concept of a singleton type in the Types chapter, before, but unrelated to Type,

3. change the section on Type{T} to explain that it is a singleton type, not "the singleton type".

[StefanKarpinski]

That seems like a good and reasonable definition. Would you be willing to make a PR to that effect?

[tpapp]

Of course, I will do it soon.