Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: Trunk
    • Fix Version/s: Trunk
    • Component/s: framework
    • Labels:
      None

      Description

      Create integrated javadocs for the applications with ant. Basically recreate in ofbiz what I did for opentaps here:

      http://www.opentaps.org/javadocs/version-0.9/framework/api/
      http://www.opentaps.org/javadocs/version-0.9/applications/api/

      The idea is to group related components together into a set of two or more javadoc builds that reference each other. (And as bonus, the core Java APIs.)

      One solution would be to normalize each component build.xml so they all have a javadoc output of $

      {basedir}/javadocs/componentName/api/. Then use the <link href=""/> element to correctly reference the relative paths so the links are generated. Each component has its own javadoc build, which can get difficult to manage.

      The other option is to group the components by related function into two or more javadoc builds such as done in the above links. (More than two because ant runs out of memory with one, even when I gave it 1GB of memory.) This would reqiure a universal build file, say ${basedir}

      /javadoc.xml. The advantages are ease of navigation and ease of customization. It is also far easier to implement than having to go and modify every build.xml.

      If the latter method is desired, I will create the instructions for ofbiz. What would be the best organization for the components in this case?

        Activity

        Leon Torres created issue -
        Hide
        Leon Torres added a comment -

        The motivation behind this is to improve documentation for developers. One of the annoyances of development is having to actually browse the source code for quick reference because the regular online javadocs are not organized and hyperlinked together in a useful fashion. Collecting related packages into one "javadoc build" is immensely useful, as well as propery hyperlinking say, the GenericDelegator object, from all the other packages.

        A secondary benefit of improving accessibility to the javadoc is that it encourages us to write more documentation.

        Show
        Leon Torres added a comment - The motivation behind this is to improve documentation for developers. One of the annoyances of development is having to actually browse the source code for quick reference because the regular online javadocs are not organized and hyperlinked together in a useful fashion. Collecting related packages into one "javadoc build" is immensely useful, as well as propery hyperlinking say, the GenericDelegator object, from all the other packages. A secondary benefit of improving accessibility to the javadoc is that it encourages us to write more documentation.
        Hide
        Leon Torres added a comment -

        Here's a patch implementing this. Run ant docs to build the javadoc.

        And here are updated links for the kind of javadoc it produces:

        http://www.opentaps.org/javadocs/version-0.9.3/framework/api/

        http://www.opentaps.org/javadocs/version-0.9.3/applications/api/

        Show
        Leon Torres added a comment - Here's a patch implementing this. Run ant docs to build the javadoc. And here are updated links for the kind of javadoc it produces: http://www.opentaps.org/javadocs/version-0.9.3/framework/api/ http://www.opentaps.org/javadocs/version-0.9.3/applications/api/
        Leon Torres made changes -
        Field Original Value New Value
        Attachment integrated-javadocs.patch [ 12346265 ]
        Hide
        Si Chen added a comment -

        Hi everybody -

        As you can see we really like this kind of layout where all the framework and applications' javadocs can be in one directory, rather than scrolling back and forth. Does anybody else like it?

        Show
        Si Chen added a comment - Hi everybody - As you can see we really like this kind of layout where all the framework and applications' javadocs can be in one directory, rather than scrolling back and forth. Does anybody else like it?
        Marco Risaliti made changes -
        Component/s framework [ 12311145 ]
        Fix Version/s SVN trunk [ 12311928 ]
        Gavin made changes -
        Workflow jira [ 12382452 ] OFbiz Workflow [ 12505170 ]
        Hide
        Marco Risaliti added a comment -

        Javadoc has been already integrated in the OFBiz build

        Show
        Marco Risaliti added a comment - Javadoc has been already integrated in the OFBiz build
        Marco Risaliti made changes -
        Status Open [ 1 ] Closed [ 6 ]
        Resolution Fixed [ 1 ]

          People

          • Assignee:
            Unassigned
            Reporter:
            Leon Torres
          • Votes:
            2 Vote for this issue
            Watchers:
            2 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development