Rename vendor error code and update documentation (#316)

Author: tiyash-basu-frequenz

proto/frequenz/api/common/v1/microgrid/electrical_components/electrical_components.proto

@@ -488,7 +488,7 @@ message ElectricalComponentDiagnostic {
 
   // Optional vendor-provided error code for the error, for vendor-specific
   // insights or more granular diagnostics.
-  optional uint32 vendor_error_code = 2;
+  optional uint32 vendor_diagnostic_code = 2;
 
   // Optional human-readable message providing additional context.
   string message = 3;
@@ -503,21 +503,33 @@ message ElectricalComponentState {
   // List of operational states currently active for the component.
   //
   // !!! note
-  //     The list must not contain duplicate state codes.
+  //    This list is treated as a set, and therefore its members will be unique,
+  //    i.e., no state will exist twice in this list.
+  //
+  // !!! note
+  //    If the state is `ELECTRICAL_COMPONENT_STATE_CODE_ERROR`, then the
+  //    electrical component is in an error state. In such cases, the `errors`
+  //    field will be populated with the list of errors.
   repeated ElectricalComponentStateCode states = 2;
 
   // List of non-critical warnings detected for the component.
   //
   // !!! note
+  //    This list is treated as a set, and therefore its members will be unique,
+  //    i.e., no state will exist twice in this list.
+  //
+  // !!! note
   //     Warnings may be reported even when the component is operational.
-  //     No duplicate warning codes allowed.
   repeated ElectricalComponentDiagnostic warnings = 3;
 
   // List of critical errors currently affecting the component.
   //
   // !!! note
-  //     This list is expected to be populated only when the component is in an
-  //     error state.
-  //     No duplicate error codes allowed.
+  //    This list is treated as a set, and therefore its members will be unique,
+  //    i.e., no state will exist twice in this list.
+  //
+  // !!! note
+  //    This list is expected to have errors if and only if the electrical
+  //    component is in an error state.
   repeated ElectricalComponentDiagnostic errors = 4;
 }

proto/frequenz/api/common/v1/microgrid/sensors/sensors.proto

@@ -173,9 +173,9 @@ message SensorDiagnostic {
   // A standardized error code representing the category of the issue.
   SensorDiagnosticCode diagnostic_code = 1;
 
-  // Optional vendor-provided error code for the error, for vendor-specific
+  // Optional vendor-provided diagnostic code for the error, for vendor-specific
   // insights or more granular diagnostics.
-  optional uint32 vendor_error_code = 2;
+  optional uint32 vendor_diagnostic_code = 2;
 
   // Optional human-readable message providing additional context.
   string message = 3;
@@ -189,30 +189,35 @@ message SensorState {
   // List of states of the microgrid sensor.
   //
   // !!! note
-  //    The list will contain unique members. No state will exist twice in
-  //    this list.
+  //    This list is treated as a set, and therefore its members will be unique,
+  //    i.e., no state will exist twice in this list.
+  //
+  // !!! note
+  //    If the state is `SENSOR_STATE_CODE_ERROR`, the sensor is in an error
+  //    state. In such cases, the `errors` field will be populated with the
+  //    list of errors.
   repeated SensorStateCode states = 2;
 
   // List of warnings for the microgrid sensor.
   //
   // !!! note
-  //    This list is expected to have warnings if and only if the sensor is
-  //    reporting warnings.
+  //    This list is treated as a set, and therefore its members will be unique,
+  //    i.e., no state will exist twice in this list.
   //
   // !!! note
-  //    The list will contain unique members. No warning will exist twice in
-  //    this list.
+  //    This list is expected to have warnings if and only if the sensor is
+  //    reporting warnings.
   repeated SensorDiagnostic warnings = 3;
 
   // List of errors for the microgrid sensor.
   //
   // !!! note
-  //    This list is expected to have errors if and only if the sensor is in
-  //    an error state.
+  //    This list is treated as a set, and therefore its members will be unique,
+  //    i.e., no state will exist twice in this list.
   //
   // !!! note
-  //    The list will contain unique members. No error will exist twice in
-  //    this list.
+  //    This list is expected to have errors if and only if the sensor is in
+  //    an error state.
   repeated SensorDiagnostic errors = 4;
 }