From 1bd4fb8f094689791e77aa76b714af9acc857cfc Mon Sep 17 00:00:00 2001
From: rusefi <rusefillc@gmail.com>
Date: Sun, 1 Sep 2019 11:59:39 -0400
Subject: [PATCH] docs & naming consistency

---
 firmware/controllers/core/common_headers.h    | 25 ++++++++++++++++---
 firmware/gen_config2.bat                      | 12 ++++++---
 firmware/integration/pid_state.txt            | 10 ++++++++
 .../{thermistor.txt => thermistor_state.txt}  |  0
 .../{trigger.txt => trigger_state.txt}        |  0
 .../{wall_fuel.txt => wall_fuel_state.txt}    |  0
 6 files changed, 41 insertions(+), 6 deletions(-)
 create mode 100644 firmware/integration/pid_state.txt
 rename firmware/integration/{thermistor.txt => thermistor_state.txt} (100%)
 rename firmware/integration/{trigger.txt => trigger_state.txt} (100%)
 rename firmware/integration/{wall_fuel.txt => wall_fuel_state.txt} (100%)

diff --git a/firmware/controllers/core/common_headers.h b/firmware/controllers/core/common_headers.h
index 101614d637..46afd2af92 100644
--- a/firmware/controllers/core/common_headers.h
+++ b/firmware/controllers/core/common_headers.h
@@ -32,16 +32,35 @@
 #include "loggingcentral.h"
 #endif /* __cplusplus */
 
-// See also 'TS_GET_STRUCT'
+/**
+ * reference to configuration parameter
+ */
 #define DISPLAY_CONFIG(x) x
-#define DISPLAY_PREFIX(x) x
+/**
+ * The main annotation of live data - reference to dynamic state variable
+ * See also 'TS_GET_STRUCT'
+ */
 #define DISPLAY_FIELD(x) x
-// we use this 'DISPLAY' macro if value is not used by C++ in current context
+/**
+ * Advanced tag to access fields within data structures
+ * "running.fuel" variable would be referenced as DISPLAY_PREFIX(running).DISPLAY_FIELD(fuel)
+ */
+#define DISPLAY_PREFIX(x) x
+
+/**
+ * we use this 'DISPLAY' macro if value is not used by C++ code in current context and we want to hide it from compiler
+ */
 #define DISPLAY(x)
 
 #define DISPLAY_TAG(x)
+/**
+ * Just a human-readable comment. '_' underscore symbols become spaces. EOL is handled as new line.
+ */
 #define DISPLAY_TEXT(x)
 #define DISPLAY_STATE(x)
+/**
+ * Reference to one of 'output' channels/standard gauges.
+ */
 #define DISPLAY_SENSOR(x) {}
 #define DISPLAY_IF(x) x
 
diff --git a/firmware/gen_config2.bat b/firmware/gen_config2.bat
index 050006e7b2..5cbf64c457 100644
--- a/firmware/gen_config2.bat
+++ b/firmware/gen_config2.bat
@@ -2,6 +2,12 @@ rem TODO better place for this stuff, more automation so that each file does not
 
 rm gen_config2.log
 
+java -DSystemOut.name=gen_config2 ^
+ -jar ../java_tools/ConfigDefinition.jar ^
+ -definition integration/pid_state.txt ^
+ -java_destination ../java_console/models/src/com/rusefi/config/generated/PidState.java ^
+ -c_destination controllers/generated/pid_state_generated.h
+
 java -DSystemOut.name=gen_config2 ^
  -jar ../java_tools/ConfigDefinition.jar ^
  -definition integration/engine_state.txt ^
@@ -10,19 +16,19 @@ java -DSystemOut.name=gen_config2 ^
 
 java -DSystemOut.name=gen_config2 ^
  -jar ../java_tools/ConfigDefinition.jar ^
- -definition integration/thermistor.txt ^
+ -definition integration/thermistor_state.txt ^
  -java_destination ../java_console/models/src/com/rusefi/config/generated/ThermistorState.java ^
  -c_destination controllers/generated/thermistor_generated.h
 
 java -DSystemOut.name=gen_config2 ^
  -jar ../java_tools/ConfigDefinition.jar ^
- -definition integration/trigger.txt ^
+ -definition integration/trigger_state.txt ^
  -java_destination ../java_console/models/src/com/rusefi/config/generated/TriggerState.java ^
  -c_destination controllers/generated/trigger_generated.h
 
 java -DSystemOut.name=gen_config2 ^
  -jar ../java_tools/ConfigDefinition.jar ^
- -definition integration/wall_fuel.txt ^
+ -definition integration/wall_fuel_state.txt ^
  -java_destination ../java_console/models/src/com/rusefi/config/generated/WallFuelState.java ^
  -c_destination controllers/generated/wall_fuel_generated.h
 
diff --git a/firmware/integration/pid_state.txt b/firmware/integration/pid_state.txt
new file mode 100644
index 0000000000..250fe3c94b
--- /dev/null
+++ b/firmware/integration/pid_state.txt
@@ -0,0 +1,10 @@
+struct_no_prefix pid_state_s
+	float iTerm;
+	float dTerm;we are remembering this only for debugging purposes
+	float target;only used for logging
+	float input;only used for logging
+	float output;only used for logging
+	float errorAmplificationCoef;
+
+
+end_struct
diff --git a/firmware/integration/thermistor.txt b/firmware/integration/thermistor_state.txt
similarity index 100%
rename from firmware/integration/thermistor.txt
rename to firmware/integration/thermistor_state.txt
diff --git a/firmware/integration/trigger.txt b/firmware/integration/trigger_state.txt
similarity index 100%
rename from firmware/integration/trigger.txt
rename to firmware/integration/trigger_state.txt
diff --git a/firmware/integration/wall_fuel.txt b/firmware/integration/wall_fuel_state.txt
similarity index 100%
rename from firmware/integration/wall_fuel.txt
rename to firmware/integration/wall_fuel_state.txt