Examining structural correctness of documentation comments in C++ programs

Tools guaranteeing the correctness of software focus almost exclusively on the syntax and the semantics of programming languages. Compilers, static analysis tools, etc. generate diagnostic messages on inconsistencies of the language elements. However, source code contains other important artifacts: comments, which are highly important to document, understand and therefore maintain the software. It is a common experience that the quality of comments erodes during the lifecycle of the software. In this paper we investigate the quality of the documentation comments, which follow a predefined strict syntax, because they are written to be processed using an external documentation generator tool. We categorize the inconsistencies identified by Doxygen - the most widespread documentation tool for C++. We define a metric to represent the quality of the comments and we investigate how this metric changes during the lifetime of a project. The aim of the research is to provide quality assurance for the non-language components of the software.