Fix Issue #148

Author: thelfer

docs/web/release-notes-3.1.md

@@ -24,3 +24,9 @@ This version is meant to be used with `TFEL` Version 5.1.
 
 Python bindings are now generated using the
 [`pybind11`](https://github.com/pybind/pybind11) library.
+
+# Issues fixed
+
+## Issue 148: [doc] better document `rdt` usage
+
+For more details, see <https://github.com/thelfer/MFrontGenericInterfaceSupport/issues/148>.

include/MGIS/Behaviour/BehaviourData.hxx

@@ -93,8 +93,17 @@ namespace mgis::behaviour {
      *   must be computed.
      */
     std::vector<real> K;
-    //! \brief proposed time step increment increase factor
-    real rdt;
+    /*!
+     * \brief proposed time step increment increase factor
+     *
+     * The calling solver shall set a suitable value on input
+     * depending on its policy **before** each call to integrate.
+     *
+     * For instance, if the solver want to limit the increase to 20% at most, it
+     * shall set it to 1.2. But setting it to 1, the solver won't allow the
+     * behaviour to request an increase of the time step.
+     */
+    real rdt = 1;
     //! \brief speed of sound (only computed if requested)
     real speed_of_sound = 0;
     //! \brief state at the beginning of the time step

include/MGIS/Behaviour/BehaviourDataView.hxx

@@ -98,7 +98,16 @@ struct mgis_bv_BehaviourDataView {
    *   stress with respect to the deformation gradient is returned
    */
   mgis_real* K;
-  //! \brief proposed time step increment increase factor
+  /*!
+   * \brief proposed time step increment increase factor
+   *
+   * The calling solver shall set a suitable value on input
+   * depending on its policy **before** each call to integrate.
+   *
+   * For instance, if the solver want to limit the increase to 20% at most, it
+   * shall set it to 1.2. But setting it to 1, the solver won't allow the
+   * behaviour to request an increase of the time step.
+   */
   mgis_real* rdt;
   //! \brief speed of sound (only computed if requested)
   mgis_real* speed_of_sound;

include/MGIS/Behaviour/MaterialDataManager.hxx

@@ -212,8 +212,17 @@ namespace mgis::behaviour {
     MaterialStateManager s1;
     //! \brief view of the stiffness matrices, if required.
     std::span<real> K;
-    //! \brief proposed time step increment increase factor
-    real rdt;
+    /*!
+     * \brief proposed time step increment increase factor
+     *
+     * The calling solver shall set a suitable value on input
+     * depending on its policy **before** each call to integrate.
+     *
+     * For instance, if the solver want to limit the increase to 20% at most, it
+     * shall set it to 1.2. But setting it to 1, the solver won't allow the
+     * behaviour to request an increase of the time step.
+     */
+    real rdt = 1;
     //! \brief view on the speed of sound.
     std::span<real> speed_of_sound;
     //! \brief number of integration points