migrate from package.html to package-info.java

Personally, I'm not sure these bring much and would recommend deleting them.

Some do bring much. Those that don't should be improved. They should tell how the package fits into the whole of JSword, especially from an architectural design perspective. We've never gotten around to it because there is always something more interesting to work on.

I think that we should have a separate issue to update all the public Javadoc to be meaningful and proper.

Meaningful: The comment tells how the item fits into the class as a whole, not merely stating the obvious.

Proper: Every parameter, return, thrown exception, parameterized type is listed (and meaningful).

Having such will make it easier for new users to use JSword.

The value of migrating to the Java 5 form is that there are only .java files under src//java.

The problem with package doc is that nobody uses it, I.e. I can't think of any open source project that does. And the second issue is that it doesn't show in eclipse when you mouse over methods etc. I d prefer to have a simple web page that summarizes the architecture.

On the usability front my main issue is the lack of a central place for accessing functionality. A service oriented approach that abstracts all internals would be my preference as it then segregates those who want to use jsword and this want to develop it.

That was my biggest hurdle to learning to use the library and I probably still underestimate what features jsword offers... a service layer would summarize What's available.