message: add comment explaining shift_scalar
diff: @@ -77,6 +77,31 @@ where
  }
  }
  +/// Inside the circuit, we have a specialized scalar multiplication which computes
  +/// either
  +///
  +/// ```
  +/// |g: G, x: G::ScalarField| g.scale(x + 2^n)
  +/// ```
  +/// if the scalar field of G is greater than the size of the base field
  +/// and
  +/// ```
  +/// |g: G, x: G::ScalarField| g.scale(2*x + 2^n)
  +/// ```
  +///
  +/// otherwise. So, if we want to actually scale by `s`, we need to apply the inverse function
  +/// of `|x| x + 2^n` (or of `|x| 2*x + 2^n` in the other case), before supplying the scalar
  +/// to our in-circuit scalar-multiplication function. This computes that inverse function.
  +/// Namely,
  +///
  +/// ```
  +/// |x: G::ScalarField| x - 2^n
  +/// ```
  +/// when the scalar field is larger than the base field and
  +/// ```
  +/// |x: G::ScalarField| (x - 2^n) / 2
  +/// ```
  +/// in the other case.
  pub fn shift_scalar<G: AffineCurve>(x: G::ScalarField) -> G::ScalarField
  where
  G::BaseField: PrimeField,
  