Ensure that Javadoc links to the manual

There should be a @checker_framework.manual Javadoc tag in every checker (namely, classes that extend BaseTypeChecker or AggregateChecker) and in every file in a qual/ or compatqual/ subdirectory. The Javadoc tag creates cross-references from the Javadoc (which may be the first thing many users see) to the manual.

The following script verifies that the documentation is present. It would be nice to add to the Jenkins continuous integration server, and to ensure that it passes before making a release.

# There should be a @checker_framework.manual Javadoc tag in every checker
# (namely, classes that extend BaseTypeChecker or AggregateChecker) 
# and in every file in a qual/ or compatqual/ subdirectory.
# File files-lacking-cfmanualtag.txt lists the files that violate this goal.
find -path '*/qual/*' -o -path '*/compatqual/*' > files-needing-cfmanual-tag-unsorted.txt
find -type f -name '*.java' -print0 | xargs -0 grep -l 'extends AggregateChecker\|extends BaseTypeChecker' >> files-needing-cfmanual-tag-unsorted.txt
grep '.java$' files-needing-cfmanual-tag-unsorted.txt | grep -v '/tests/' | grep -v '/jtreg/' | grep -v '/docs/examples/' | grep -v '/common/util/' | grep -v '/framework/flow/' | sort | uniq > files-needing-cfmanual-tag.txt
find -type f -name '*.java' -print0 | xargs -0 grep -l '@checker_framework.manual' | sort > files-having-cfmanual-tag.txt
diff files-needing-cfmanual-tag.txt files-having-cfmanual-tag.txt | grep '^<' | sed 's/^< //' | sed 's/\.java$/.java:1: class Javadoc needs: @checker_framework.manual #sectionref Section title/' > files-lacking-cfmanualtag.txt

To examine the files, run
cat files-lacking-cfmanualtag.txt

Original issue reported on code.google.com by michael.ernst@gmail.com on 3 Mar 2015 at 6:21

Start by running the supplied find, grep, and diff commands, then inspect files-lacking-cfmanualtag.txt to identify the affected Java files. Review the Javadoc conventions in those checker, qual, and compatqual files and the Jenkins configuration. Done means every required file has the tag and the verification passes before release.