From 840ef0869e4b36f097d57cc66ebac3b7c5014934 Mon Sep 17 00:00:00 2001
From: Christian Heinrich <franz-christian.heinrich@inria.fr>
Date: Tue, 26 May 2015 19:39:31 +0200
Subject: [PATCH] [SMPI] Added several document blocks for ois, or and ois

- I hope this makes it easier to understand what is going
  on here!
---
 src/smpi/smpi_base.c | 34 ++++++++++++++++++++++++++++------
 1 file changed, 28 insertions(+), 6 deletions(-)

diff --git a/src/smpi/smpi_base.c b/src/smpi/smpi_base.c
index 84edb27fe1..a31b752314 100644
--- a/src/smpi/smpi_base.c
+++ b/src/smpi/smpi_base.c
@@ -135,12 +135,19 @@ static double smpi_os(double size)
   unsigned int iter = 0;
   s_smpi_factor_t fact;
   double current=0.0;
+  // Iterate over all the sections that were specified and find the right
+  // value. (fact.factor represents the interval sizes; we want to find the
+  // section that has fact.factor <= size and no other such fact.factor <= size)
+  // Note: parse_factor() (used before) already sorts the dynar we iterate over!
   xbt_dynar_foreach(smpi_os_values, iter, fact) {
-    if (size <= fact.factor) {
+    if (size <= fact.factor) { // Values already too large, use the previously
+                               // computed value of current!
         XBT_DEBUG("os : %f <= %ld return %f", size, fact.factor, current);
       return current;
     }else{
-      current=fact.values[0]+fact.values[1]*size;
+      // If the next section is too large, the current section must be used.
+      // Hence, save the cost, as we might have to use it.
+      current = fact.values[0]+fact.values[1]*size;
     }
   }
   XBT_DEBUG("os : %f > %ld return %f", size, fact.factor, current);
@@ -157,12 +164,19 @@ static double smpi_ois(double size)
   unsigned int iter = 0;
   s_smpi_factor_t fact;
   double current=0.0;
+  // Iterate over all the sections that were specified and find the right
+  // value. (fact.factor represents the interval sizes; we want to find the
+  // section that has fact.factor <= size and no other such fact.factor <= size)
+  // Note: parse_factor() (used before) already sorts the dynar we iterate over!
   xbt_dynar_foreach(smpi_ois_values, iter, fact) {
-    if (size <= fact.factor) {
+    if (size <= fact.factor) { // Values already too large, use the previously
+                               // computed value of current!
         XBT_DEBUG("ois : %f <= %ld return %f", size, fact.factor, current);
       return current;
     }else{
-      current=fact.values[0]+fact.values[1]*size;
+      // If the next section is too large, the current section must be used.
+      // Hence, save the cost, as we might have to use it.
+      current = fact.values[0]+fact.values[1]*size;
     }
   }
   XBT_DEBUG("ois : %f > %ld return %f", size, fact.factor, current);
@@ -179,12 +193,20 @@ static double smpi_or(double size)
   unsigned int iter = 0;
   s_smpi_factor_t fact;
   double current=0.0;
+  // Iterate over all the sections that were specified and find the right
+  // value. (fact.factor represents the interval sizes; we want to find the
+  // section that has fact.factor <= size and no other such fact.factor <= size)
+  // Note: parse_factor() (used before) already sorts the dynar we iterate over!
   xbt_dynar_foreach(smpi_or_values, iter, fact) {
-    if (size <= fact.factor) {
+    if (size <= fact.factor) { // Values already too large, use the previously
+                               // computed value of current!
         XBT_DEBUG("or : %f <= %ld return %f", size, fact.factor, current);
       return current;
-    }else
+    } else {
+      // If the next section is too large, the current section must be used.
+      // Hence, save the cost, as we might have to use it.
       current=fact.values[0]+fact.values[1]*size;
+    }
   }
   XBT_DEBUG("or : %f > %ld return %f", size, fact.factor, current);
 
-- 
2.20.1