Document generic type argument inference

ponyc PR #5974 adds type argument inference for generic method and
constructor calls. The tutorial's generics overview now covers the
feature: when it applies, how it interacts with type parameter defaults,
and the cases where explicit type arguments are still required.

Author: SeanTAllen

code-samples/generics-type-argument-inference-constructor.pony

@@ -0,0 +1,20 @@
+class Foo[A: Any val]
+  var _c: A
+
+  new create(c: A) =>
+    _c = c
+
+  fun get(): A => _c
+
+  fun ref set(c: A) => _c = c
+
+actor Main
+  new create(env: Env) =>
+    let a = Foo(42)
+    env.out.print(a.get().string())
+
+    let b = Foo(1.5)
+    env.out.print(b.get().string())
+
+    let c = Foo("Hello")
+    env.out.print(c.get().string())

code-samples/generics-type-argument-inference-defaults.pony

@@ -0,0 +1,14 @@
+class Bar[A: Any box = USize val]
+  var _c: A
+
+  new create(c: A) =>
+    _c = c
+
+  fun get(): A => _c
+
+  fun ref set(c: A) => _c = c
+
+actor Main
+  new create(env: Env) =>
+    let a = Bar(42)       // A is USize because the argument fits the default
+    let b = Bar(F32(1.5)) // A is F32 because the argument overrides the default

code-samples/generics-type-argument-inference-method.pony

@@ -0,0 +1,11 @@
+primitive Foo
+  fun bar[A: Stringable val](a: A): String =>
+    a.string()
+
+actor Main
+  new create(env: Env) =>
+    let a = Foo.bar(U32(10))
+    env.out.print(a.string())
+
+    let b = Foo.bar("Hello")
+    env.out.print(b.string())

docs/generics/index.md

@@ -25,7 +25,7 @@ The first thing to note here is that the `Foo` class now takes a type parameter
 
 In this case, the name is `A`, the constraint is `Any` and the reference capability is `val`. `Any` is used to mean that the type can be any type - it is not constrained. The remainder of the class definition replaces `U32` with the type name `A`.
 
-The user of the class must provide a type when referencing the class name. This is done when creating it:
+The user of the class provides a type when referencing the class name, or lets the compiler [infer it from the arguments](#type-argument-inference). Here the type is provided explicitly:
 
 ```pony
 --8<--
@@ -69,3 +69,52 @@ Methods can be generic too. They are defined in the same way as normal methods b
 This example shows a constraint other than `Any`. The `Stringable` type is any type with a `string()` method to convert to a `String`.
 
 These examples show the basic idea behind generics and how to use them. Real world usage gets quite a bit more complex and the following sections will dive deeper into how to use them.
+
+## Type Argument Inference
+
+When each type argument can be determined from the arguments at the call site, you can omit the type arguments. The generic methods example above includes explicit type arguments:
+
+```pony
+--8<-- "generics-generic-methods.pony:7:7"
+```
+
+With inference, `A` resolves to `U32` from the argument `U32(10)`, so the type argument can be omitted:
+
+```pony
+--8<-- "generics-type-argument-inference-method.pony:7:7"
+```
+
+The argument is `U32(10)` rather than the bare `10` from the explicit example — a bare integer literal defaults to `USize`, so `Foo.bar(10)` would resolve `A` to `USize`.
+
+The same applies to constructor calls. The `Foo` class from earlier can be constructed without writing the type argument:
+
+```pony
+--8<--
+generics-type-argument-inference-constructor.pony:13:13
+generics-type-argument-inference-constructor.pony:16:16
+generics-type-argument-inference-constructor.pony:19:19
+--8<--
+```
+
+### Interaction with defaults
+
+When a type parameter has a default and the argument fits the default type, the default is kept. When the argument does not fit, the inferred type replaces the default:
+
+```pony
+--8<-- "generics-type-argument-inference-defaults.pony:13:14"
+```
+
+In the first line, `42` fits `USize` (the default), so `A` stays `USize`. In the second line, `F32(1.5)` does not fit `USize`, so `A` becomes `F32`.
+
+### When inference does not apply
+
+At least one argument must determine each type parameter. When inference fails, the compiler reports an error — write the type arguments explicitly to resolve it. Cases where inference does not apply:
+
+- The type parameter does not appear in any parameter type (it only appears in the return type, for example).
+- The argument at the determining position is an array literal or lambda whose own type depends on the type parameter being inferred. This includes type parameters that appear only in a lambda's result type.
+- The parameter type refers to the type parameter through a type alias.
+- The parameter type is a union.
+- The argument is passed with the `where` keyword (named-only arguments).
+- A generic method is called on a type whose own type parameters use defaults and are written without type arguments — add explicit type arguments to either the type or the method.
+
+You can always write the type arguments explicitly — inference is a convenience, not a requirement.