Details

    • Type: Improvement
    • Status: Closed
    • Priority: Minor
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 2.3
    • Component/s: general/javadocs
    • Labels:
      None
    • Lucene Fields:
      New, Patch Available

      Description

      A while ago we had a discussion on java-dev about separating the javadocs
      for the contrib modules instead of having only one big javadoc containing
      the core and contrib classes.

      This patch:

      • Adds new targets to build.xml:
        • "javadocs-all" Generates Javadocs for the core, demo, and contrib
          classes
        • "javadocs-core" Generates Javadocs for the core classes
        • "javadocs-demo" Generates Javadocs for the demo classes
        • "javadocs-contrib" Using contrib-crawl it generates the Javadocs for
          all contrib modules, except "similarity" (currently empty) and gdata.
      • Adds submenues to the Javadocs link on the Lucene site with links to
        the different javadocs
      • Includes the javadocs in the maven artifacts

      Remarks:

      • I removed the ant target "javadocs-internal", because I didn't want to
        add corresponding targets for all new javadocs target. Instead I
        defined a new property "javadoc.access", so now
        "ant -Djavadoc.access=package" can be used in combination with any of
        the javadocs targets. Is this ok?
      • I didn't include gdata (yet) because it uses build files that don't
        extend Lucenes standard build files.

      Here's a preview:
      http://people.apache.org/~buschmi/site-preview/index.html

      Please let me know what you think about these changes!

      1. lucene-1051-take2.patch
        23 kB
        Michael Busch
      2. lucene-1051.patch
        23 kB
        Michael Busch

        Issue Links

          Activity

          Hide
          gsingers Grant Ingersoll added a comment -

          OK, this should be up live on the site now. I still have to check into why the site isn't being copied properly. Will do when I get back from ApacheCon.

          Show
          gsingers Grant Ingersoll added a comment - OK, this should be up live on the site now. I still have to check into why the site isn't being copied properly. Will do when I get back from ApacheCon.
          Hide
          michaelbusch Michael Busch added a comment -

          Committed.

          Show
          michaelbusch Michael Busch added a comment - Committed.
          Hide
          michaelbusch Michael Busch added a comment - - edited

          The take2 patch works fine for me.

          Thanks for trying! I will commit then...

          the note about keeping the contrib list uptodate with the group list should also mention keeping the list in site.xml uptodate.

          Agreed. I'll update the comment.

          Show
          michaelbusch Michael Busch added a comment - - edited The take2 patch works fine for me. Thanks for trying! I will commit then... the note about keeping the contrib list uptodate with the group list should also mention keeping the list in site.xml uptodate. Agreed. I'll update the comment.
          Hide
          michaelbusch Michael Busch added a comment -

          Are many folks using Lucene's gdata server? If no one is using it, and it's not maintained, then it should probably be dropped from trunk. If someone decides to start maintaining it later, then they could update it and re-add it to trunk.

          +1

          Show
          michaelbusch Michael Busch added a comment - Are many folks using Lucene's gdata server? If no one is using it, and it's not maintained, then it should probably be dropped from trunk. If someone decides to start maintaining it later, then they could update it and re-add it to trunk. +1
          Hide
          hossman Hoss Man added a comment -

          the note about keeping the contrib list uptodate with the group list should also mention keeping the list in site.xml uptodate.

          we could probably make that site.xml list autogenerated by the javadoc target, but that would require someone with ant fu and forrest fu thinking about it carefully ... in the meantime a reminder note would be handy.

          Show
          hossman Hoss Man added a comment - the note about keeping the contrib list uptodate with the group list should also mention keeping the list in site.xml uptodate. we could probably make that site.xml list autogenerated by the javadoc target, but that would require someone with ant fu and forrest fu thinking about it carefully ... in the meantime a reminder note would be handy.
          Hide
          paul.elschot@xs4all.nl Paul Elschot added a comment -

          The take2 patch works fine for me. Also this works fine:
          ant -Djavadoc.access=private javadocs-core
          but it generates two minor javadoc warnings.

          Grant:
          ant javadocs generates everything combined and everything seperately,
          and ant javadocs-contrib works as expected.

          Show
          paul.elschot@xs4all.nl Paul Elschot added a comment - The take2 patch works fine for me. Also this works fine: ant -Djavadoc.access=private javadocs-core but it generates two minor javadoc warnings. Grant: ant javadocs generates everything combined and everything seperately, and ant javadocs-contrib works as expected.
          Hide
          cutting Doug Cutting added a comment -

          > we should decide on how we're going to maintain gdata

          Are many folks using Lucene's gdata server? If no one is using it, and it's not maintained, then it should probably be dropped from trunk. If someone decides to start maintaining it later, then they could update it and re-add it to trunk.

          Show
          cutting Doug Cutting added a comment - > we should decide on how we're going to maintain gdata Are many folks using Lucene's gdata server? If no one is using it, and it's not maintained, then it should probably be dropped from trunk. If someone decides to start maintaining it later, then they could update it and re-add it to trunk.
          Hide
          michaelbusch Michael Busch added a comment -

          Looks good. I think we need to put GData in before committing.

          GData has build files that don't extend common-build.xml, so there's always extra work that needs to be done when we add a new feature to our build (like maven artifacts or these javadocs improvements). It doesn't seem that Simon is still around, but we should decide on how we're going to maintain gdata. I'll open a new issue for that and not put GData in this patch.

          Also, I don't know ANT well enough, but is there anyway to have it automatically do the contrib packages without having to explicitly specify it? Just one less thing to remember to add when adding new contrib packages. If it's not a quick fix, don't worry about.

          Hmm, not sure how to do that. There's a TODO comment in the build file for a long time. I think I'll commit this patch and we can simplify that in the future if someone knows who to do this with Ant.

          Show
          michaelbusch Michael Busch added a comment - Looks good. I think we need to put GData in before committing. GData has build files that don't extend common-build.xml, so there's always extra work that needs to be done when we add a new feature to our build (like maven artifacts or these javadocs improvements). It doesn't seem that Simon is still around, but we should decide on how we're going to maintain gdata. I'll open a new issue for that and not put GData in this patch. Also, I don't know ANT well enough, but is there anyway to have it automatically do the contrib packages without having to explicitly specify it? Just one less thing to remember to add when adding new contrib packages. If it's not a quick fix, don't worry about. Hmm, not sure how to do that. There's a TODO comment in the build file for a long time. I think I'll commit this patch and we can simplify that in the future if someone knows who to do this with Ant.
          Hide
          gsingers Grant Ingersoll added a comment -

          Looks good. I think we need to put GData in before committing.

          Also, I don't know ANT well enough, but is there anyway to have it automatically do the contrib packages without having to explicitly specify it? Just one less thing to remember to add when adding new contrib packages. If it's not a quick fix, don't worry about.

          Show
          gsingers Grant Ingersoll added a comment - Looks good. I think we need to put GData in before committing. Also, I don't know ANT well enough, but is there anyway to have it automatically do the contrib packages without having to explicitly specify it? Just one less thing to remember to add when adding new contrib packages. If it's not a quick fix, don't worry about.
          Hide
          paul.elschot@xs4all.nl Paul Elschot added a comment -

          This has been somewhere far down on my todo list for quite a while, so I was going to try the patch, but a committed version would certainly be easier. In case you prefer someone else to try this before committing, could you wait a (short) week?

          Show
          paul.elschot@xs4all.nl Paul Elschot added a comment - This has been somewhere far down on my todo list for quite a while, so I was going to try the patch, but a committed version would certainly be easier. In case you prefer someone else to try this before committing, could you wait a (short) week?
          Hide
          michaelbusch Michael Busch added a comment -

          I'm planning to commit this tomorrow... any objections? Did anyone look at the preview yet?

          Show
          michaelbusch Michael Busch added a comment - I'm planning to commit this tomorrow... any objections? Did anyone look at the preview yet?
          Hide
          michaelbusch Michael Busch added a comment -

          Some small improvements:

          • Moved property "javadoc.link" to common-build.xml, so that
            the link is available in the contrib javadocs as well.
          • Linked the core, demo, and contrib javadocs with the
            combined javadocs, which makes these javadocs much nicer.
          • The combined javadocs now go into the same directory as
            before, so bookmarks will still work after we applied this
            patch.

          I also updated the preview.

          Show
          michaelbusch Michael Busch added a comment - Some small improvements: Moved property "javadoc.link" to common-build.xml, so that the link is available in the contrib javadocs as well. Linked the core, demo, and contrib javadocs with the combined javadocs, which makes these javadocs much nicer. The combined javadocs now go into the same directory as before, so bookmarks will still work after we applied this patch. I also updated the preview.

            People

            • Assignee:
              michaelbusch Michael Busch
              Reporter:
              michaelbusch Michael Busch
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development