JSword
  1. JSword
  2. JS-261

migrate from package.html to package-info.java

    Details

    • Type: Improvement Improvement
    • Status: Closed (View Workflow)
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 1.7
    • Component/s: None
    • Labels:
      None

      Description

      Java 5 introduced package-info.java as a replacement for package.html.

        Activity

        Hide
        Chris Burrell added a comment -

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

        Show
        Chris Burrell added a comment - Personally, I'm not sure these bring much and would recommend deleting them.
        Hide
        DM Smith added a comment -

        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.

        Show
        DM Smith added a comment - 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.
        Hide
        Chris Burrell added a comment -

        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.

        Show
        Chris Burrell added a comment - 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.

          People

          • Assignee:
            DM Smith
            Reporter:
            DM Smith
          • Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved: