Document all perturb() instances

include/core/problem/problem.h

@@ -366,7 +366,10 @@ class Problem : public std::enable_shared_from_this<Problem>
 
 
         // All branches -------------------------------------------
-        // perturb states
+        /**
+         *  \brief perturb all states states with random noise
+         * following an uniform distribution in [ -amplitude, amplitude ]
+         */
         void perturb(double amplitude = 0.01);
         // transform states
         void transform(const VectorComposite& _transformation);

include/core/state_block/has_state_blocks.h

@@ -97,7 +97,10 @@ class HasStateBlocks
         unsigned int getSize(const StateStructure& _structure="") const;
         unsigned int getLocalSize(const StateStructure& _structure="") const;
 
-        // Perturb state
+        /**
+         *  \brief perturb all states states with random noise
+         * following an uniform distribution in [ -amplitude, amplitude ]
+         */
         void perturb(double amplitude = 0.01);        
 
       protected:

include/core/state_block/state_block.h

@@ -176,7 +176,9 @@ public:
         virtual Eigen::VectorXd identity() const;
         Eigen::VectorXd zero()     const;
 
-        /** \brief perturb state
+        /**
+         *  \brief perturb all states states with random noise
+         * following an uniform distribution in [ -amplitude, amplitude ]
          */
         void perturb(double amplitude = 0.1);
 

include/core/state_block/state_composite.h

@@ -314,7 +314,10 @@ class StateBlockComposite
         // Plus operator
         void                    plus(const VectorComposite& _dx);
 
-        // Perturb state with random noise
+        /**
+         *  \brief perturb all states states with random noise
+         * following an uniform distribution in [ -amplitude, amplitude ]
+         */
         void                    perturb(double amplitude = 0.01);
 
         // These act on all state blocks. Per-block action must be done through state_block.fix() or through extended API in derived classes of this.