RfC: Create OBD error code documentation automatically from firmware source code during release process

[mi-hol]

For maintainers keeping documentation in sync with firmware releases is currently a tedious, labor intensive and error prone task because it is fully manual work!

For users nothing is more frustrating as getting an error code that has no documentation as it basically stops every targeted troubleshooting activity the user could perform to get going again quickly and with minimal effort.

To achieve FOME's quality goal automation is required to solve this issue.

Solution idea:

1. transform C++ header file containing all actively used OBD error codes into a validated machine readable structured format (i.e. XML) using a standard parser (i.e. swig)
2. create a utility tool to transform validated machine readable structured format into markdown format used for wiki
3. run above steps automatically during release process preventing out-of-sync situations

Would there be any comments regarding solution or suggestions for technical implementation?

[mi-hol]

First test:

to implement 1. in above:

PS C:\Users\mholzer\Documents\git\fome-fw> ."C:\Program Files\swigwin-4.1.1\swig.exe" -c++ -module obd_error_codes -xml -o obd_error_codes.xml firmware/controllers/algo/obd_error_codes.h

obd_error_codes.xml.zip

Benefit:

all inactive (=commented) error codes are not part of validated machine readable structured format !

    //P0089 Fuel Pressure Regulator 1 Performance
    OBD_Fuel_Pressure_Sensor_Missing = 90,
    //P0091 Fuel Pressure Regulator 1 Control Circuit Low
    //P0092 Fuel Pressure Regulator 1 Control Circuit High
    //P0093 Fuel System Leak Detected - Large Leak
    //P0094 Fuel System Leak Detected - Small Leak
    //P0095 Intake Air Temperature Sensor 2 Circuit
    //P0096 Intake Air Temperature Sensor 2 Circuit Range/Performance
    //P0097 Intake Air Temperature Sensor 2 Circuit Low
    //P0098 Intake Air Temperature Sensor 2 Circuit High
    //P0099 Intake Air Temperature Sensor 2 Circuit Intermittent/Erratic
    OBD_Mass_or_Volume_Air_Flow_Circuit_Malfunction = 100,
    //P0101 Mass or Volume Air Flow Circuit Range/Performance Problem

[mi-hol]

to implement 2. in above

a XMLreader would:

1. extract the attributes names and values listed below
2. output them as a markdown table in a file to include in wiki

example:

<attribute name="name" value="OBD_Fuel_Pressure_Sensor_Missing"  />
<attribute name="enumvalue" value="90"  />

for 1. XPath query seems the solution

for 2. will try to leverage for output from https://github.com/wadackel/gha-docgen/blob/main/src/docgen.ts#L92