From: Jean-Paul Pelteret <jppelteret@gmail.com>
Date: Tue, 22 Jan 2019 15:17:45 +0000 (+0100)
Subject: Improve documentation in AD drivers header
X-Git-Tag: v9.1.0-rc1~389^2~4
X-Git-Url: https://gitweb.dealii.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e2ae49cbf79e256343543906b09a2d6c1a8890a2;p=dealii.git

Improve documentation in AD drivers header
---

diff --git a/include/deal.II/differentiation/ad/ad_drivers.h b/include/deal.II/differentiation/ad/ad_drivers.h
index 5af046665b..7f76fe8461 100644
--- a/include/deal.II/differentiation/ad/ad_drivers.h
+++ b/include/deal.II/differentiation/ad/ad_drivers.h
@@ -279,10 +279,31 @@ namespace Differentiation
        * Return a flag that, when <code>true</code>, indicates that the retaping
        * of the dependent function for the chosen @p tape_index is necessary for
        * a reliable computation to be performed.
-       * 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.
+       *
        * @note The chosen tape index must be greater than
        * Numbers<ADNumberType>::invalid_tape_index and less than
        * Numbers<ADNumberType>::max_tape_index.
@@ -295,9 +316,30 @@ 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 active tape.
-       * 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.
        */
       bool
       last_action_requires_retaping() const;
@@ -869,6 +911,8 @@ namespace Differentiation
        *
        * When the @p status variable takes a negative value, retaping of the dependent
        * function is necessary for a reliable computation to be performed.
+       * This status can be queried through the requires_retaping() and
+       * last_action_requires_retaping() functions.
        */
       mutable std::map<typename Types<ADNumberType>::tape_index, int> status;