Improve documentation to AD helpers header.

diff --git a/include/deal.II/differentiation/ad/ad_helpers.h b/include/deal.II/differentiation/ad/ad_helpers.h
index c8bd16a31b7d1270d914ccca038123e953296cad..ac716dfd94c2fe146fdfa3c83462829f18f7068f 100644 (file)
--- a/include/deal.II/differentiation/ad/ad_helpers.h
+++ b/include/deal.II/differentiation/ad/ad_helpers.h
@@ -482,12 +482,33 @@ namespace Differentiation
        * Return a flag that, when <code>true</code>, indicates that the
        * retaping of the dependent function is necessary for a reliable
        * computation to be performed on a tape with the given @p tape_index.
-       * This may be necessary a sign comparison within branched operations
+       * This may be necessary if a sign comparison within branched operations
        * yields different results to those computed at the original tape
        * evaluation point.
        *
+       * This issue, known as "branch switching", can be clarified by means of
+       * a trivial example:
+       * @code
+       * ADNumberType func (ADNumberType x, ADNumberType y, ADNumberType z)
+       * {
+       *   if (x < y)
+       *     return y;
+       *   else
+       *     return x*z;
+       * }
+       * @endcode
+       * During taping, the conditional statement may be either <tt>true</tt> or
+       * <tt>false</tt>, and the result (with its sensitivities) returned by
+       * this function. For some other evaluation of the tape (i.e. for some
+       * different
+       * inputs @p x and @p y, the other branch of the conditional check may be
+       * chosen. The result of following this code path has not been recorded on
+       * the tape, and therefore cannot be evaluated. In such a case, it is
+       * therefore necessary to re-record the tape at the new evaluation point
+       * in order to resolve the new code branch.
+       *
        * For the output of this function to be meaningful, it must be called
-       * after the activate_recorded_tape() is called and the new evaluation
+       * after activate_recorded_tape() is called and the new evaluation
        * point for the tape (i.e. values of the independent variables) have
        * been set and subsequently used (i.e. in the determination of the values
        * or derivatives of the dependent variables).
@@ -499,12 +520,34 @@ namespace Differentiation
       /**
        * Return a flag that, when <code>true</code>, indicates that the
        * retaping of the dependent function is necessary for a reliable
-       * computation to be performed on the avtive tape. This may be necessary a
-       * sign comparison within branched operations yields different results to
-       * those computed at the original tape evaluation point.
+       * computation to be performed on the active tape.
+       * This may be necessary if a sign comparison within branched operations
+       * yields different results to those computed at the original tape
+       * evaluation point.
+       *
+       * This issue, known as "branch switching", can be clarified by means of
+       * a trivial example:
+       * @code
+       * ADNumberType func (ADNumberType x, ADNumberType y, ADNumberType z)
+       * {
+       *   if (x < y)
+       *     return y;
+       *   else
+       *     return x*z;
+       * }
+       * @endcode
+       * During taping, the conditional statement may be either <tt>true</tt> or
+       * <tt>false</tt>, and the result (with its sensitivities) returned by
+       * this function. For some other evaluation of the tape (i.e. for some
+       * different
+       * inputs @p x and @p y, the other branch of the conditional check may be
+       * chosen. The result of following this code path has not been recorded on
+       * the tape, and therefore cannot be evaluated. In such a case, it is
+       * therefore necessary to re-record the tape at the new evaluation point
+       * in order to resolve the new code branch.
        *
        * For the output of this function to be meaningful, it must be called
-       * after the activate_recorded_tape() is called and the new evaluation
+       * after activate_recorded_tape() is called and the new evaluation
        * point for the tape (i.e. values of the independent variables) have
        * been set and subsequently used (i.e. in the determination of the values
        * or derivatives of the dependent variables).