Type System Documentation Overhaul

[BoxyUwU]

This issue is intended to be used as a bit of a central thread for my ongoing work to write a bunch of docs for type system stuff and make sure existing docs we have are up to date. A corresponding zulip thread can be found here: #t-compiler/rustc-dev-guide > Type System Docs Rewrite

This is part of the "Type System Documentation" project goal: rust-lang/rust-project-goals#405

This is an unordered list of general type system concepts that should have documentation in the dev guide. Some may already have pages in the dev guide and so their presence here just means they should be looked over for missing/incorrect/confusing information. Thanks to lcnr for helping put together the initial list:

• opaque types
  • non defining vs defining uses
  • member constraints (borrowck overlap)
  • checking item bounds
  • high level normalization/opaque type storage approach (new solver)
  • normalization incompleteness
  • method/function incompleteness
  • how does use<...> work
  • 'erased regions causes problems with outlives item bounds in liveness
  • consistency across defining scopes
  • RPITIT inference? does this have special stuff
  • capturing of bound vars in opaques under binders, Fn bounds are somewhat special in relation to this
  • opaques inheriting late bound function parameters
• non opaque type, impl Trait
  • RPITIT in traits desugaring
  • impl Trait in bindings
  • APIT desugaring impl details
• const generics
  • parsing/nameres/ast-lowering jank Initial docs for const generics #2677
  • (implicit) defcollector jank around _/N array lengths
  • mgca stuff?
  • anonymous constants Initial docs for const generics #2677
  • ConstArgHasType Initial docs for const generics #2677
  • TSVs vs RVs and generally upstream doc from lang meeting to dev guide
  • deterministic CTFE requirement Initial docs for const generics #2677
• HIR typeck
  • expectations (and how used incorrectly :3)
  • method lookup + assorted code cleanups
  • coercions add coercions chapter and split out non hir typeck stuff #2662
  • auto-deref/reborrows (in coercions/method selection)
  • closure signature inference
  • fudge_inference_if_ok :>
  • diverging block handling :3
  • fallback :3
• MIR borrowck
  • MIR typeck
    • why do we want two typecks
    • region dependent goals in new solver (interaction with lack-of region uniquification)
  • overlaps with opaque types
  • verifys/type tests
  • compute region graph
  • closure requirements
  • borrowck proper
• compare predicate entailment :>
  • param env jank
  • implied bounds handling
• trait objects: recent FCPs :3
  • dyn compatibility soundness interactions (see coerce pointee/arbitrary self types stuff)
  • dyn compatibility for impl reasons (monomorphization)
  • projection bounds handling
  • args not required for wf
• ty::Infer in ty overview
• generalization
  • cc explain generalization when talking about type inference #1820
• coroutines
  • deferred coroutine obligations
  • witness types?
  • why -Zhigher-ranked-assumptions exists
• binders and universes existsA forallB A == B
  • build more of an intuition than current docs :thinking_face:
• talk about hr implied bounds there/be more explicit/clear in https://rustc-dev-guide.rust-lang.org/traits/implied-bounds.html?highlight=implied#proving-implicit-implied-bounds
• incompleteness
  • what is it
  • what kinds are OK (not entirely sure yet. small explanation and add a note)
• trait solving
  • cycles
  • general overview of how trait solving works as a concept (probably with example and handwritten proof trees)
    • important: first go "prove stuff by recursively proving nested requirements", then later introduce candidates
    • clauses/predicates
  • running pending goals in a loop
  • what kinds of incompleteness (overlap with opaques)
• hir to ty lowering :>
  • cc Document HIR ty lowering #178
  • itemctxt vs fnctxt behaviours
  • normalization in lowering
  • lowering should be lossy
  • idempotency(?)
  • cycles from param env construction
  • const generics jank about Self and no generic parameters allowed
• well formedness checking + wf disambiguation page
• normalization & aliases
  • be more clear about normalizing ambig aliases to infer vars :thinking_face:
  • normalize when equating infer vars with aliases (overlap with generalization?)
  • item bounds checking
  • interactions with implied bounds (overlap with implied bounds and hir ty lowering)
  • talk about opaqueness of aliases as a separate concept from opaque types which are sort of a blend of opaqueness and global inference
• some kind of "adding a new builtin trait" walkthrough chapter
• variance
• leak checking
  • cc move lcnrs leak check fcp to dev guide #2003
• canonicalization & PsuedoCanonicalQuery stuff

cc #1184 #1161 #704