From 3a9096aa41f8e32c5f822999979ed15084e650d4 Mon Sep 17 00:00:00 2001
From: Andrew Tridgell <tridge@samba.org>
Date: Fri, 15 Jun 2012 11:54:13 +1000
Subject: [PATCH] APM: added longer comment on k_format_version

---
 ArduPlane/Parameters.h | 35 +++++++++++++++++++++++++++--------
 1 file changed, 27 insertions(+), 8 deletions(-)

diff --git a/ArduPlane/Parameters.h b/ArduPlane/Parameters.h
index 85dd9ab267..4c4cc94e59 100644
--- a/ArduPlane/Parameters.h
+++ b/ArduPlane/Parameters.h
@@ -9,15 +9,34 @@
 //
 class Parameters {
 public:
-    // The version of the layout as described by the parameter enum.
-    //
-    // When changing the parameter enum in an incompatible fashion, this
-    // value should be incremented by one.
-    //
-    // The increment will prevent old parameters from being used incorrectly
-    // by newer code.
-    //
+
+    /*
+      The value of k_format_version determines whether the existing
+      eeprom data is considered valid. You should only change this
+      value under the following circumstances:
+
+     1) the meaning of an existing eeprom parameter changes
+
+     2) the value of an existing k_param_* enum value changes
+
+     Adding a new parameter should _not_ require a change to
+     k_format_version except under special circumstances. If you
+     change it anyway then all ArduPlane users will need to reload all
+     their parameters. We want that to be an extremely rare
+     thing. Please do not just change it "just in case".
+
+     To determine if a k_param_* value has changed, use the rules of
+     C++ enums to work out the value of the neighboring enum
+     values. If you don't know the C++ enum rules then please ask for
+     help.
+    */
+
+    //////////////////////////////////////////////////////////////////
+    // STOP!!! DO NOT CHANGE THIS VALUE UNTIL YOU FULLY UNDERSTAND THE
+    // COMMENTS ABOVE. IF UNSURE, ASK ANOTHER DEVELOPER!!!
     static const uint16_t k_format_version = 13;
+    //////////////////////////////////////////////////////////////////
+
 
 	// The parameter software_type is set up solely for ground station use
 	// and identifies the software type (eg ArduPilotMega versus ArduCopterMega)