[PATCH] Planner: Add comments to document the code
Rick Walsh
rickmwalsh at gmail.com
Mon Jul 27 05:06:02 PDT 2015
The purpose of parts of the planner code is not not always obvious. This is
especially true of the conditional statements in the add_plan_to_notes function.
Annotate the code with comments to explain the logic.
Signed-off-by: Rick Walsh <rickmwalsh at gmail.com>
---
planner.c | 46 ++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 46 insertions(+)
diff --git a/planner.c b/planner.c
index c2cfe74..377b868 100644
--- a/planner.c
+++ b/planner.c
@@ -595,6 +595,12 @@ static void add_plan_to_notes(struct diveplan *diveplan, struct dive *dive, bool
len = strlen(buffer);
if (plan_verbatim) {
+ /* When displaying a verbatim plan, we output a waypoint for every gas change.
+ * Therefore, we do not need to test for difficult cases that mean we need to
+ * print a segment just so we don't miss a gas change. This makes the logic
+ * to determine whether or not to print a segment much simpler than with the
+ * non-verbatim plan.
+ */
if (dp->depth != lastprintdepth) {
if (plan_display_transitions || dp->entered || !dp->next || (gaschange_after && dp->next && dp->depth != nextdp->depth)) {
if (dp->setpoint)
@@ -638,6 +644,22 @@ static void add_plan_to_notes(struct diveplan *diveplan, struct dive *dive, bool
}
}
} else {
+ /* When not displaying the verbatim dive plan, we typically ignore ascents between deco stops,
+ * unless the display transitions option has been selected. We output a segment if any of the
+ * following conditions are met.
+ * 1) Display transitions is selected
+ * 2) The segment was manually entered
+ * 3) It is the last segment of the dive
+ * 4) The segment is not an ascent, there was a gas change at the start of the segment and the next segment
+ * is a change in depth (typical deco stop)
+ * 5) There is a gas change at the end of the segment and the last segment was entered (first calculated
+ * segment if it ends in a gas change)
+ * 6) There is a gaschange after but no ascent. This should only occur when backgas breaks option is selected
+ * 7) It is an ascent ending with a gas change, but is not followed by a stop. As case 5 already matches
+ * the first calculated ascent if it ends with a gas change, this should only occur if a travel gas is
+ * used for a calculated ascent, there is a subsequent gas change before the first deco stop, and zero
+ * time has been allowed for a gas switch.
+ */
if (plan_display_transitions || dp->entered || !dp->next ||
(nextdp && dp->depth != nextdp->depth) ||
(!isascent && gaschange_before && nextdp && dp->depth != nextdp->depth) ||
@@ -654,6 +676,9 @@ static void add_plan_to_notes(struct diveplan *diveplan, struct dive *dive, bool
len += snprintf(buffer + len, sizeof(buffer) - len, "<td style='padding-left: 10px; float: right;'>%s</td>", temp);
}
+ /* Normally a gas change is displayed on the stopping segment, so only display a gas change at the end of
+ * an ascent segment if it is not followed by a stop
+ */
if (isascent && gaschange_after && dp->next && nextdp && dp->depth != nextdp->depth) {
if (dp->setpoint) {
snprintf(temp, sizeof(temp), translate("gettextFromC", "(SP = %.1fbar)"), (double) nextdp->setpoint / 1000.0);
@@ -666,6 +691,7 @@ static void add_plan_to_notes(struct diveplan *diveplan, struct dive *dive, bool
lastprintgasmix = newgasmix;
gaschange_after = false;
} else if (gaschange_before) {
+ // If a new gas has been used for this segment, now is the time to show it
if (dp->setpoint) {
snprintf(temp, sizeof(temp), translate("gettextFromC", "(SP = %.1fbar)"), (double) dp->setpoint / 1000.0);
len += snprintf(buffer + len, sizeof(buffer) - len, "<td style='padding-left: 10px; color: red; float: left;'><b>%s %s</b></td>", gasname(&gasmix),
@@ -673,6 +699,7 @@ static void add_plan_to_notes(struct diveplan *diveplan, struct dive *dive, bool
} else {
len += snprintf(buffer + len, sizeof(buffer) - len, "<td style='padding-left: 10px; color: red; float: left;'><b>%s</b></td>", gasname(&gasmix));
}
+ // Set variables so subsequent iterations can test against the last gas printed
lastprintsetpoint = dp->setpoint;
lastprintgasmix = gasmix;
gaschange_after = false;
@@ -824,6 +851,7 @@ void track_ascent_gas(int depth, cylinder_t *cylinder, int avg_depth, int bottom
}
}
+// Determine whether ascending to the next stop will break the ceiling. Return true if the ascent is ok, false if it isn't.
bool trial_ascent(int trial_depth, int stoplevel, int avg_depth, int bottom_time, double tissue_tolerance, struct gasmix *gasmix, int po2, double surface_pressure)
{
@@ -854,6 +882,10 @@ bool trial_ascent(int trial_depth, int stoplevel, int avg_depth, int bottom_time
return clear_to_ascend;
}
+/* Determine if there is enough gas for the dive. Return true if there is enough.
+ * Also return true if this cannot be calculated because the cylinder doesn't have
+ * size or a starting pressure.
+ */
bool enough_gas(int current_cylinder)
{
cylinder_t *cyl;
@@ -909,6 +941,7 @@ bool plan(struct diveplan *diveplan, char **cached_datap, bool is_planner, bool
diveplan->surface_pressure = SURFACE_PRESSURE;
create_dive_from_plan(diveplan, is_planner);
+ // Do we want deco stop array in metres or feet?
if (prefs.units.length == METERS ) {
decostoplevels = decostoplevels_metric;
decostoplevelcount = sizeof(decostoplevels_metric) / sizeof(int);
@@ -917,6 +950,9 @@ bool plan(struct diveplan *diveplan, char **cached_datap, bool is_planner, bool
decostoplevelcount = sizeof(decostoplevels_imperial) / sizeof(int);
}
+ /* If the user has selected last stop to be at 6m/20', we need to get rid of the 3m/10' stop.
+ * Otherwise reinstate the last stop 3m/10' stop.
+ */
if (prefs.last_stop)
*(decostoplevels + 1) = 0;
else
@@ -1124,6 +1160,9 @@ bool plan(struct diveplan *diveplan, char **cached_datap, bool is_planner, bool
if (prefs.doo2breaks && get_o2(&displayed_dive.cylinder[current_cylinder].gasmix) == 1000)
o2time += prefs.min_switch_duration;
} else {
+ /* The user has selected the option to switch gas only at required stops.
+ * Remember that we are waiting to switch gas
+ */
pendinggaschange = true;
}
gi--;
@@ -1148,6 +1187,10 @@ bool plan(struct diveplan *diveplan, char **cached_datap, bool is_planner, bool
previous_point_time = clock;
stopping = true;
}
+
+ /* Are we waiting to switch gas?
+ * Occurs when the user has selected the option to switch only at required stops
+ */
if (pendinggaschange) {
current_cylinder = gaschanges[gi + 1].gasidx;
gas = displayed_dive.cylinder[current_cylinder].gasmix;
@@ -1179,6 +1222,9 @@ bool plan(struct diveplan *diveplan, char **cached_datap, bool is_planner, bool
break;
}
if (prefs.doo2breaks) {
+ /* The backgas breaks option limits time on oxygen to 12 minutes, followed by 6 minutes on
+ * backgas (first defined gas). This could be customized if there were demand.
+ */
if (get_o2(&displayed_dive.cylinder[current_cylinder].gasmix) == 1000) {
o2time += DECOTIMESTEP;
if (o2time >= 12 * 60) {
--
2.4.3
More information about the subsurface
mailing list