Abstract: Code comments are important artifacts in software. Java has standardized the writing of API specifications as Javadoc comments. API developers write Javadoc comments, and API users often read these comments to understand the API they use, e.g., reading a Javadoc comment for a method instead of reading the body of the method. An inconsistency between the Javadoc comment and body for a method indicates either a fault in the body or, effectively, a fault in the comment that can mislead the callers of the method to introduce faults in their code.
We present a novel approach, called @tComment, for testing Javadoc comments, specifically for testing method properties about null values and related exceptions. Our approach consists of two components. Given source files for a Java project, the first component automatically analyzes the English text in each Javadoc comment to infer a set of likely properties for each method in the files. The second component generates random tests for these methods, checks the inferred properties, and reports inconsistencies. We evaluated @tComment on six opensource projects and found 24 inconsistencies between Javadoc comments and method bodies. We reported all of these inconsistencies, and 12 have already been confirmed and fixed by the developers.
@inproceedings{tan2012tcomment,
title={@ tcomment: Testing javadoc comments to detect comment-code inconsistencies},
author={Tan, Shin Hwei and Marinov, Darko and Tan, Lin and Leavens, Gary T},
booktitle={2012 IEEE Fifth International Conference on Software Testing, Verification and Validation},
pages={260--269},
year={2012},
organization={IEEE}
}