fix java doc problems in projects
javadoc problems exist in the following projects and should be fixed (see also #6240 this is not a duplicate!). The reference on all existing javadoc tags: http://docs.oracle.com/javase/1.5.0/docs/tooldocs/windows/javadoc.html#javadoctags
In order to properly test for existing problems you may need to diable the fix applied in cdmlib|99f6d80
Projects with problems:
- cdmlib TODO
- cdm-vaadin TODO
- cdm-servver TODO
- cdm-dataportal TODO
List of problems:
* @date tag is not officially supported --> remove or replace?
* broken @link references (151x in cdmlib) these should be fixed. Do not delete them!
#9 Updated by Andreas Müller over 2 years ago
Andreas Kohlbecker wrote:
Andreas Müller wrote:
A solution might be to replace all "* @date " by "* @since "
The doc says the since text is free, so we could use it for the creation date, but usually one would rather expect a version number for since.
That is true. But maybe we should start handling it this way. Version numbers are more useful than dates. However, the question is how we get eclipse to know the current version number and how if we want to update the existing tags.
I think we can live with existing tags being changed to @since with the given date.
For new tags it would be nice to have version number instead of date if possible.
#34 Updated by Patrick Plitzner over 1 year ago
- Status changed from New to Feedback
- Assignee changed from Patrick Plitzner to Andreas Müller
We should discuss if it is really necessary to fix the broken links. I also took a quick look and it seems that in most cases there is one broken link in one class file. I think this is too much work for a non critical issue
#36 Updated by Andreas Kohlbecker about 1 year ago
There are far less problems as you've assumed after having a quick look.
mvn javadoc:javadoc reports 294 broken @links for which reference classes or methods. This does not include test classes.
Maven provides a tool to interactively fix problems in javadoc tags (https://maven.apache.org/plugins/maven-javadoc-plugin/fix-mojo.html) which is supposed to also fix @link tags.
I did a test run of this tool. I did not fix the broken @links but it does a lot of other useful things. I think we should run this on our projects with selected parameters.