OpenVAS Change Request #19: Agree on a style guideline and on a format for the documentationStatus: Voted + 5, in the OpenVAS Compendium Rev. 2100.
To ease further developement of all OpenVAS modules.
To improve readability of source code.
To have an appropriate section in the OpenVAS Compendium for the people interested in making OpenVAS even better.
- Discussion on mailinglist.
- The GNU Coding Standards, Formatting section
- Code Style Guide section in the OpenVAS Compendium.
- Small comment on mailing list.
- Doxygen, the proposed automatic source code documentator.
In the OpenVAS code base one can find that too many different conventions about code formatting and code documentation were used. This makes it difficult for developers that are new to the OpenVAS project to look at the code and get a fast overview. Furthermore, there is a certain lack of documentation, and no extensive documentation of the API exists.
There are guidelines given in the OpenVAS Compendium, but the section is short and no "standard" is stated.
If the currently active developers agree on one style (e.g. on one favorite file) this can be set as a standard for future developements and documented in the OpenVAS Compendium.
This agreement and enhanced section in the OpenVAS Compendium allows current source developements to look the same, thus enhancing readability and reducing the currently high demand of reading and understanding the code at the same time.
Furthermore it allows to use tools to automatically extract an API documentation, which in turn can help the developers to understand OpenVAS. If this API documentation reaches a certain quality, it can be made available online and become included into -dev or -doc packages.
Future developements would thus look the same and be documented. Old code, however, would stay untouched. Style changes would become applied gradually, e.g. when code in the same file is touched, to not make svn blames too difficult.
Design and Implementation
After discussions on the developers mailinglist, agreement fell on the GNU Coding Style Guide and the use of doxygen with Javadoc- style comments.
A standard Doxyfile was added to the repository.
The OpenVAS Compendium was updated.
- 2008-12-29 Felix Wolfsteller <firstname.lastname@example.org>:
Updated as voted upon.
- 2008-12-16 Felix Wolfsteller <email@example.com>:
Updated the highlighted example to be GNUier.
- 2008-11-19 Felix Wolfsteller <firstname.lastname@example.org>:
Small change (gchar *str should have been gchar* str), reference to highlighter.
- 2008-11-18 Felix Wolfsteller <email@example.com>: