Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Description parametrized #92

Open
andcaspe opened this issue Dec 2, 2024 · 0 comments
Open

Description parametrized #92

andcaspe opened this issue Dec 2, 2024 · 0 comments
Labels
enhancement New feature or request

Comments

@andcaspe
Copy link

andcaspe commented Dec 2, 2024

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,
  1. 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:

descript_field_static_code

For dynamic code:

description_field

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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

1 participant