Description parametrized

[andcaspe]

Describe the problem

The current implementation in the Cbexigen repository requires manual population of the description field within the documentation for every .c/.h file. This value is always set to "Description goes here", leading to unnecessary repetition and inefficiency.

Impact:

• Increased Effort: Developers need to manually enter the placeholder text, which can cause that they have to repeat the documentation phase each time the code is generated.
• Inconsistency: Manual entry adds a risk of inconsistent formatting or incomplete descriptions across files when the code is generated and documented several times.

Describe your solution

Implementation

To address this issue and streamline the documentation process, we suggest two approaches:

1. Base Description for Static Code:

Update the CommonFileHeader.jinja template to include a new "description" block that can be extended or inherited by other Jinja templates. This way, if the "description" block remains unchanged in the child templates, the default behavior will persist.
This approach promotes code reusability and maintains consistency for static code documentation.

{% block description %}
/**
  * @file {{ filename }}
  * @brief {{ description or "Description goes here" }}
  *
  **/
{% endblock description %}

2. Dynamic Description Injection:

For dynamic code (converter, encoder, and decoder files), we propose injecting the description variable directly during Jinja template rendering using a mechanism like config.py.
This allows dynamic descriptions based on specific code functionalities, making the documentation more informative and adaptable.
There are two files that could be updated:

1. datatype_classes.py injecting the description parameter

            temp = self.generator.get_template('BaseDatatypes.h.jinja')
            code = temp.render(filename=self.h_params['filename'],
                               filekey=self.h_params['identifier'],
                               description=self.h_params.get('description'),
                               include=include,
                               defines=defines,
                               enum_code=enum_code,

2. config.py adding the description key when needed

    'appHand_Datatypes': {
        'schema': 'ISO_15118-2/FDIS/V2G_CI_AppProtocol.xsd',
        'prefix': 'appHand_',
        'type': 'converter',
        'folder': 'appHandshake',
        'h': {
            'filename': 'appHand_Datatypes.h',
            'identifier': 'APP_HANDSHAKE_DATATYPES_H',
            'description': 'Datatype definitions and structs for given XML Schema definitions and initialization methods',
            'include_std_lib': ['stddef.h', 'stdint.h'],
            'include_other': []
        },
        'c': {
            'filename': 'appHand_Datatypes.c',
            'identifier': 'APP_HANDSHAKE_DATATYPES_C',
            'include_std_lib': [],
            'include_other': ['appHand_Datatypes.h']
        }
    },

Benefits:

• Reduced Manual Effort: Developers will be relieved of the need to write the placeholder description repeatedly, saving time and minimizing errors.
• Improved Consistency: By employing a centralized base description or configuration injection, we can ensure consistent descriptions across all files.
• Enhanced Readability: Dynamic descriptions tailored to specific code sections will make the documentation more informative and user-friendly.

Results with the proposed solution

For static code:

For dynamic code:

Additional context

If it might be helpful, I tried to open a pull request with the proposed changes, which are backward compatible with the previous code. Any feedback would be appreciated!