docs: Clarify important points about parametric types

Closes JuliaLang#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)

Author: adigitoleo

base/docs/basedocs.jl

@@ -2569,7 +2569,7 @@ converted to type `T` by calling [`convert`](@ref).
 In a method declaration, the syntax `function f(x)::T` causes any value returned by
 the method to be converted to type `T`.
 
-See the manual section on [Type Declarations](@ref).
+See the manual section on [Type Annotations](@ref).
 
 # Examples
 ```jldoctest

doc/src/index.md

@@ -64,13 +64,13 @@ The most significant departures of Julia from typical dynamic languages are:
   * The core language imposes very little; Julia Base and the standard library are written in Julia itself, including
     primitive operations like integer arithmetic
   * A rich language of types for constructing and describing objects, that can also optionally be
-    used to make type declarations
+    used to write type annotations
   * The ability to define function behavior across many combinations of argument types via [multiple dispatch](https://en.wikipedia.org/wiki/Multiple_dispatch)
   * Automatic generation of efficient, specialized code for different argument types
   * Good performance, approaching that of statically-compiled languages like C
 
 Although one sometimes speaks of dynamic languages as being "typeless", they are definitely not:
-every object, whether primitive or user-defined, has a type. The lack of type declarations in
+every object, whether primitive or user-defined, has a type. The lack of type annotations in
 most dynamic languages, however, means that one cannot instruct the compiler about the types of
 values, and often cannot explicitly talk about types at all. In static languages, on the other
 hand, while one can -- and usually must -- annotate types for the compiler, types exist only at

doc/src/manual/faq.md

@@ -359,7 +359,7 @@ julia> twothreearr()
  3
 ```
 
-## Types, type declarations, and constructors
+## Types, type annotations, and constructors
 
 ### [What does "type-stable" mean?](@id man-type-stability)
 

doc/src/manual/functions.md

@@ -63,20 +63,20 @@ are identical to the passed values. Modifications to mutable values (such as `Ar
 a function will be visible to the caller. This is the same behavior found in Scheme, most Lisps,
 Python, Ruby and Perl, among other dynamic languages.
 
-## Argument-type declarations
+## Argument-type annotations
 
-You can declare the types of function arguments by appending `::TypeName` to the argument name, as usual for [Type Declarations](@ref) in Julia.
+You can declare the types of function arguments by appending `::TypeName` to the argument name, as usual for [Type Annotations](@ref) in Julia.
 For example, the following function computes [Fibonacci numbers](https://en.wikipedia.org/wiki/Fibonacci_number) recursively:
 ```
 fib(n::Integer) = n ≤ 2 ? one(n) : fib(n-1) + fib(n-2)
 ```
 and the `::Integer` specification means that it will only be callable when `n` is a subtype of the [abstract](@ref man-abstract-types) `Integer` type.
 
-Argument-type declarations **normally have no impact on performance**: regardless of what argument types (if any) are declared, Julia compiles a specialized version of the function for the actual argument types passed by the caller.   For example, calling `fib(1)` will trigger the compilation of specialized version of `fib` optimized specifically for `Int` arguments, which is then re-used if `fib(7)` or `fib(15)` are called.  (There are rare exceptions when an argument-type declaration can trigger additional compiler specializations; see: [Be aware of when Julia avoids specializing](@ref).)  The most common reasons to declare argument types in Julia are, instead:
+Argument-type annotations **normally have no impact on performance**: regardless of what argument types (if any) are declared, Julia compiles a specialized version of the function for the actual argument types passed by the caller.   For example, calling `fib(1)` will trigger the compilation of specialized version of `fib` optimized specifically for `Int` arguments, which is then re-used if `fib(7)` or `fib(15)` are called.  (There are rare exceptions when an argument-type annotation can trigger additional compiler specializations; see: [Be aware of when Julia avoids specializing](@ref).)  The most common reasons to declare argument types in Julia are, instead:
 
 * **Dispatch:** As explained in [Methods](@ref), you can have different versions ("methods") of a function for different argument types, in which case the argument types are used to determine which implementation is called for which arguments.  For example, you might implement a completely different algorithm `fib(x::Number) = ...` that works for any `Number` type by using [Binet's formula](https://en.wikipedia.org/wiki/Fibonacci_number#Binet%27s_formula) to extend it to non-integer values.
-* **Correctness:** Type declarations can be useful if your function only returns correct results for certain argument types.  For example, if we omitted argument types and wrote `fib(n) = n ≤ 2 ? one(n) : fib(n-1) + fib(n-2)`, then `fib(1.5)` would silently give us the nonsensical answer `1.0`.
-* **Clarity:** Type declarations can serve as a form of documentation about the expected arguments.
+* **Correctness:** Type annotations can be useful if your function only returns correct results for certain argument types.  For example, if we omitted argument types and wrote `fib(n) = n ≤ 2 ? one(n) : fib(n-1) + fib(n-2)`, then `fib(1.5)` would silently give us the nonsensical answer `1.0`.
+* **Clarity:** Type annotations can serve as a form of documentation about the expected arguments.
 
 However, it is a **common mistake to overly restrict the argument types**, which can unnecessarily limit the applicability of the function and prevent it from being re-used in circumstances you did not anticipate.    For example, the `fib(n::Integer)` function above works equally well for `Int` arguments (machine integers) and `BigInt` arbitrary-precision integers (see [BigFloats and BigInts](@ref BigFloats-and-BigInts)), which is especially useful because Fibonacci numbers grow exponentially rapidly and will quickly overflow any fixed-precision type like `Int` (see [Overflow behavior](@ref)).  If we had declared our function as `fib(n::Int)`, however, the application to `BigInt` would have been prevented for no reason.   In general, you should use the most general applicable abstract types for arguments, and **when in doubt, omit the argument types**.  You can always add argument-type specifications later if they become necessary, and you don't sacrifice performance or functionality by omitting them.
 
@@ -161,9 +161,9 @@ Int8
 ```
 
 This function will always return an `Int8` regardless of the types of `x` and `y`.
-See [Type Declarations](@ref) for more on return types.
+See [Type Annotations](@ref) for more on return types.
 
-Return type declarations are **rarely used** in Julia: in general, you should
+Return type annotations are **rarely used** in Julia: in general, you should
 instead write "type-stable" functions in which Julia's compiler can automatically
 infer the return type.  For more information, see the [Performance Tips](@ref man-performance-tips) chapter.
 

doc/src/manual/methods.md

@@ -181,7 +181,7 @@ which shows that `f` has two methods, one taking two `Float64` arguments and one
 of type `Number`. It also indicates the file and line number where the methods were defined: because
 these methods were defined at the REPL, we get the apparent line number `none:1`.
 
-In the absence of a type declaration with `::`, the type of a method parameter is `Any` by default,
+In the absence of a type annotation with `::`, the type of a method parameter is `Any` by default,
 meaning that it is unconstrained since all values in Julia are instances of the abstract type
 `Any`. Thus, we can define a catch-all method for `f` like so:
 

doc/src/manual/performance-tips.md

@@ -201,12 +201,12 @@ better than `IdDict{Type, Vector}`
 
 See also the discussion under [Parametric Types](@ref).
 
-## Type declarations
+## Type annotations
 
-In many languages with optional type declarations, adding declarations is the principal way to
+In many languages with optional type annotations, adding declarations is the principal way to
 make code run faster. This is *not* the case in Julia. In Julia, the compiler generally knows
 the types of all function arguments, local variables, and expressions. However, there are a few
-specific instances where declarations are helpful.
+specific instances where annotations are helpful.
 
 ### Avoid fields with abstract type