docs: Clarify important points about parametric types

[adigitoleo]

Closes #43811.

• The intro section felt a bit long-winded, I've made some changes there first.
• Clarify that typeof returns the concrete type
• Rename Type Declarations section to Type Annotations,
  avoid confusion with Declaring Types section and distinguish use of "type declaration"
  to mean "declaring new types"
• Removed some of the jargon and wikipedia links to make room for
  a brief alternative Point{T1,T2} demonstration.
• Shifted some paragraphs around to reflect their importance,
  and changed the wording in some places.
• Rename type declaration -> annotation in other places (docstrings/comments)

[adigitoleo]

Couldn't find a good place to add a complete custom type family example, and the section is already quite long. Maybe that can go somewhere else eventually.

[adigitoleo]

One other thing I left out compared to the linked issue was talking about DataType, because that has it's own section in Declaring Types.

I do think that Declaring Types needs a bit of work as well, but I'll leave it for another PR.

[StefanKarpinski]

This seems fairly good, but https://github.com/JuliaLang/julia/pull/43891/files#diff-ff6fac0d94f573935b4028dee9bd538f1e1527fde287a3e247394dc16a7fc701 is quite hard to review because of the formatting changes. I guess I'll have to read the whole thing to make sure it makes sense and also check that it doesn't delete anything important from the original.

[adigitoleo]

Happy to revert the formatting if it helps. I automatically adopted my markdown habits of breaking at sentence clauses, which I find to produce comfy diffs (except for the first time it's done, like here).

Here's the built html of that page, if it helps: https://x0.at/Bw6y.txt

[StefanKarpinski]

That would be great if you could. I also prefer that style, but it makes the diff here too big and hard to read. You could separate the change into purely formatting and actual content changes as well and then I can just review the content change.

[fingolfin]

Overall this looks quite good to me! It is a pity that it sat around here for almost 2 years :-(. @adigitoleo sorry for that, if you are still willing to work on it, perhaps you can resolve the conflict?

@StefanKarpinski I think this is relatively nice to review now, perhaps you'd be willing to have another look at it?

[adigitoleo]

Thanks for the review. Conflicts should be resolved now. I've addressed the comments, but I'm not sure of the etiquette: should I mark conversations as resolved or leave that to maintainers?

[oscardssmith]

I think this is ready to merge, right?

[adigitoleo]

Just rebased on lates master, haven't looked at the bulk of the changes in a while but it has been reviewed before. Should be good to go from my side.

[stevengj]

Explicit annotations are not required in many statically typed languages, e.g. with Hindley–Milner type systems, which (like Julia) use type inference.

The difference, as @StefanKarpinski has often put it, is that in a static language it is an error if type inference fails, whereas in a dynamic language like Julia the inference is just an optimization.

[adigitoleo]

Good points, thanks. How about this for the first paragraph:

Types in Julia establish distinctions between different kinds of data, and are used by the compiler to infer the intended use of those data. Programming languages have traditionally employed one of two quite different type systems: static type systems, where expressions must have a computable type before the execution of the program, and dynamic type systems, where types are only computed at run time, when the actual values manipulated by the program are available. Statically typed languages typically offer faster execution of programs, while treating any data of unknown or invalid type as an error. In these languages, the programmer is responsible for ensuring the validity of all types of data that the program may encounter. Dynamically typed languages, on the other hand, do not explicitly check types, and types of data only become invalid when they fail to support run-time operations.

[stevengj]

Statically typed languages typically offer faster execution of programs

The whole point of Julia is that this is not true — they are not any faster than type-stable code in Julia. The main argument for static typing, IMO, is safety — by being stricter about types, the compiler can catch more bugs. (And, of course, there are tradeoffs, e.g. in making interactive exploration more difficult.)

But the pros and cons of static vs. dynamic languages is a longstanding debate and a bit of a can of worms here.

[adigitoleo]

I guess by "typically" I probably meant "usually", but I can understand if this unintentionally suggests that Julia is not performant. I'll think about a better wording here.

[fingolfin]

I don't think "usually" is any better

[adigitoleo]

Statically typed languages offer stricter guidance for avoiding unsafe code, such as treating any data of unknown or invalid type as an error. In these languages, the programmer is responsible for ensuring the validity of all types of data that the program may encounter. Writing programs in statically typed languages is, therefore, more laborious, and interactive exploration of data at run-time becomes more difficult. Dynamically typed languages, on the other hand, do not explicitly check types, and types of data only become invalid when they fail to support run-time operations. This provides a more flexible and productive programming experience, at the cost of a greater potential for programmer errors to cause bugs during execution.

?

[adienes]

Suggested change

	the relation `Foo{Float64} <: Foo{Real}` does NOT hold for any parametric type `Foo`.
	the relation `Foo{Float64} <: Foo{Real}` does NOT hold for any parametric type `Foo`.

of course except for Tuple

[adigitoleo]

I didn't know about that, thanks. Is there a reason why that is the case that we can/should highlight here?

[adienes]

I'm not familiar with all the details but my understanding is that the reason for covariance is largely vestigial; it made dispatch easier in the early days of Julia or something

Tuple type covariance is described here in the docs https://docs.julialang.org/en/v1/manual/types/#Tuple-Types-1

and there is an open issue discussing the potential to switch to invariance in a hypothetical breaking release of Julia (although as a gambling man, I wouldn't put my money on that change ever happening) #24614

I would think a quick link to the docs is probably sufficient

[adigitoleo]

Thanks again everyone, a few minor points to clarify from the review by @adienes and about the first paragraph (@stevengj, see #43891 (comment)).