Caleb Williams
2016-09-18 03:00:00 UTC
Hey all:
I have just finished the bulk of the work needed to update the FreeCol
Javadoc sources (see
https://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/index.html
for those unfamiliar with Javadoc) to a more modern format. The HTML within
the Javadoc sources has been made more standards compliant as well.
The largest change was moving from the package.html format to the
package-info.java format. This change moves FreeCol to the preferred method
of package-level annotation. At the same time, I made sure to review almost
all of these new files to make sure they were using HTML and CSS properly.
Some package annotations contained a small amount of information with very
little formatting, but the larger annotations were all looked at and
updated as needed. A few typos were fixed as part of this process, but by
and large the actual content did not change.
Additionally, I cleaned up a large group of about 50 to 60 Javadoc errors
and warnings that largely consisted of missing or incorrect parameter tags.
Also, the use of depreciated <code>CODE</code> tags were replaced with the
preferred {@code CODE} format.
Finally, after discussion with the primary developer, Mike Pope, a change
made to remove unneeded {@inheritDoc} tags was reverted as he will use
those tags later as FreeCol approaches release.
There is still some work needed, especially with annotation parameters of
<T> generics but in many cases those changes will need to be made by a
developer more experienced in Java than I.
Best wishes to all those reading this,
I have just finished the bulk of the work needed to update the FreeCol
Javadoc sources (see
https://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/index.html
for those unfamiliar with Javadoc) to a more modern format. The HTML within
the Javadoc sources has been made more standards compliant as well.
The largest change was moving from the package.html format to the
package-info.java format. This change moves FreeCol to the preferred method
of package-level annotation. At the same time, I made sure to review almost
all of these new files to make sure they were using HTML and CSS properly.
Some package annotations contained a small amount of information with very
little formatting, but the larger annotations were all looked at and
updated as needed. A few typos were fixed as part of this process, but by
and large the actual content did not change.
Additionally, I cleaned up a large group of about 50 to 60 Javadoc errors
and warnings that largely consisted of missing or incorrect parameter tags.
Also, the use of depreciated <code>CODE</code> tags were replaced with the
preferred {@code CODE} format.
Finally, after discussion with the primary developer, Mike Pope, a change
made to remove unneeded {@inheritDoc} tags was reverted as he will use
those tags later as FreeCol approaches release.
There is still some work needed, especially with annotation parameters of
<T> generics but in many cases those changes will need to be made by a
developer more experienced in Java than I.
Best wishes to all those reading this,
--
*Caleb R. Williams*
*Caleb R. Williams*