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?

[stevengj]

Maybe:

Type annotations are important for defining efficient new data structures, can help enforce correctness and clarity, and can sometimes improve efficiency (although in many contexts the Julia compiler infers types automatically). However, type annotations also play a central role in Julia because they control method dispatch: functions can be extended to new behaviors for different argument types.

[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 also have polymorphism and generic programming.

[adigitoleo]

See above suggestion, wherein I removed the misleading reference to polymorphism.

[stevengj]

Suggested change

	both [`isabstracttype`](@ref) and [`isconcretetype`](@ref) will return false.
	both [`isabstracttype`](@ref) and [`isconcretetype`](@ref) will return `false`.