rewrite combine doc comment

compiler/rustc_infer/src/infer/combine.rs

@@ -1,26 +1,26 @@
-///////////////////////////////////////////////////////////////////////////
+//! There are four type combiners: [Equate], [Sub], [Lub], and [Glb].
-// # Type combining
+//! Each implements the trait [TypeRelation] and contains methods for
-//
+//! combining two instances of various things and yielding a new instance.
-// There are four type combiners: equate, sub, lub, and glb.  Each
+//! These combiner methods always yield a `Result<T>`. To relate two
-// implements the trait `Combine` and contains methods for combining
+//! types, you can use `infcx.at(cause, param_env)` which then allows
-// two instances of various things and yielding a new instance.  These
+//! you to use the relevant methods of [At](super::at::At).
-// combiner methods always yield a `Result<T>`.  There is a lot of
+//!
-// common code for these operations, implemented as default methods on
+//! Combiners mostly do their specific behavior and then hand off the
-// the `Combine` trait.
+//! bulk of the work to [InferCtxt::super_combine_tys] and
-//
+//! [InferCtxt::super_combine_consts].
-// Each operation may have side-effects on the inference context,
+//!
-// though these can be unrolled using snapshots. On success, the
+//! Combining two types may have side-effects on the inference contexts
-// LUB/GLB operations return the appropriate bound. The Eq and Sub
+//! which can be undone by using snapshots. You probably want to use
-// operations generally return the first operand.
+//! either [InferCtxt::commit_if_ok] or [InferCtxt::probe].
-//
+//!
-// ## Contravariance
+//! On success, the  LUB/GLB operations return the appropriate bound. The
-//
+//! return value of `Equate` or `Sub` shouldn't really be used.
-// When you are relating two things which have a contravariant
+//!
-// relationship, you should use `contratys()` or `contraregions()`,
+//! ## Contravariance
-// rather than inversing the order of arguments!  This is necessary
+//!
-// because the order of arguments is not relevant for LUB and GLB.  It
+//! We explicitly track which argument is expected using
-// is also useful to track which value is the "expected" value in
+//! [TypeRelation::a_is_expected], so when dealing with contravariance
-// terms of error reporting.
+//! this should be correctly updated.
 
 use super::equate::Equate;
 use super::glb::Glb;