While fixing the existing javadoc comments, I started wondering how are we going to arrange things so that developers get all the support they need for writing valid javadocs? Maybe this problem has already been solved but I just wanted to ask to be sure.
I’m not yet very familiar with the CI process here and was wondering what is the visibility of javadoc compilation errors to your average OpenMRS developer? For example, if a developer implements some changes, does the pull request etc, when and how will said committer get notified that her modifications caused a javadoc compilation error?
Ideally the developer should see javadoc errors a) immediately in the IDE or b) latest at “mvn install”. Regarding a), I gave Eclipse’s javadoc validation a try (see Preferences, Java, Compiler, Javadoc) but could not get it to use the same validation logic as “javadoc:aggregate-jar” does. Regarding b), I guess “mvn install” is not hooked up to javadoc validation at the moment but maybe it should?
To give you some perspective, based on the number and type of javadoc errors I have been fixing in TRUNK-4711, I would be as bold as to say there is not a single person on this project who can write valid javadocs without feedback from the validator. And that also includes yours truly!