You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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:
datatype_classes.py injecting the description parameter
'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!
The text was updated successfully, but these errors were encountered:
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:
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.
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:
Benefits:
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!
The text was updated successfully, but these errors were encountered: