Details

    • Type: Improvement Improvement
    • Status: Open
    • Priority: Major Major
    • Resolution: Unresolved
    • Affects Version/s: 3.2, 4.0-ALPHA
    • Fix Version/s: None
    • Component/s: None
    • Labels:
      None

      Description

      We should fail the build when there are javadocs warnings, as this should not be the Release Manager's job to fix all at once right before the release.

      See http://www.lucidimagination.com/search/document/14bd01e519f39aff/brainstorming_on_improving_the_release_process

      1. LUCENE-3006.patch
        5 kB
        Grant Ingersoll
      2. LUCENE-3006.patch
        3 kB
        Grant Ingersoll
      3. LUCENE-3006.patch
        49 kB
        Grant Ingersoll
      4. LUCENE-3006-javadoc-warning-cleanup.patch
        6 kB
        Steve Rowe
      5. LUCENE-3006-modules-javadoc-warning-cleanup.patch
        2 kB
        Steve Rowe

        Activity

        Hide
        Michael McCandless added a comment -

        +1

        Show
        Michael McCandless added a comment - +1
        Hide
        Yonik Seeley added a comment -

        One nit - javadocs for solr are not nearly as important as javadocs for lucene in general, and are often just there for expert / internal developers. But I don't know how onerous it will be to fail on jdoc warning yet... maybe it won't be a big deal.

        Show
        Yonik Seeley added a comment - One nit - javadocs for solr are not nearly as important as javadocs for lucene in general, and are often just there for expert / internal developers. But I don't know how onerous it will be to fail on jdoc warning yet... maybe it won't be a big deal.
        Show
        Steve Rowe added a comment - Doron Cohen briefly enabled fail-on-javadocs-warnings a few years back: https://issues.apache.org/jira/browse/LUCENE-875?focusedCommentId=12493779&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-12493779
        Hide
        Yonik Seeley added a comment -

        We should fail the build when there are javadocs warnings

        Hopefully you mean the build of javadoc should fail? It seems like one should be able to do a quick change of a method to try something out and still be able to do "ant test" to see if it works w/o having to go fix all javadoc references to it first?

        Show
        Yonik Seeley added a comment - We should fail the build when there are javadocs warnings Hopefully you mean the build of javadoc should fail? It seems like one should be able to do a quick change of a method to try something out and still be able to do "ant test" to see if it works w/o having to go fix all javadoc references to it first?
        Hide
        Grant Ingersoll added a comment -

        Build hook in to javadoc. Doesn't fix the warnings, which need to be fixed.

        Show
        Grant Ingersoll added a comment - Build hook in to javadoc. Doesn't fix the warnings, which need to be fixed.
        Hide
        Grant Ingersoll added a comment -

        Adds a property to only fail if failonjavadocwarning is true (which is the default setting).

        Show
        Grant Ingersoll added a comment - Adds a property to only fail if failonjavadocwarning is true (which is the default setting).
        Hide
        Grant Ingersoll added a comment -

        I think this is ready to go, but still want to test to make sure contribs are building correctly. Also, committing it will break the build, as we have warnings on trunk!

        Show
        Grant Ingersoll added a comment - I think this is ready to go, but still want to test to make sure contribs are building correctly. Also, committing it will break the build, as we have warnings on trunk!
        Hide
        Steve Rowe added a comment -

        I'm working on cleaning up javadoc warnings on trunk, and found a longstanding Sun javadoc bug that is hit by the javadoc on the FieldInfos no-arg constructor:

        /**
          * ...
          * Note: this ctor should not be used during indexing use
          * {@link FieldInfos#FieldInfos(FieldInfos)} or
          * {@link FieldInfos#FieldInfos(FieldNumberBiMap)} instead.
          */
        

        Javadoc complains that it can't find the second linked-to constructor.

        There are two problems: first, there really is no constructor with that prototype - it should have a second parameter of type SegmentCodecsBuilder; and second, adding the SegmentCodecsBuilder parameter doesn't make the warning go away, because of this bug: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4464323.

        Spelling out the SegmentCodecsBuilder parameter's full package works around this bug under both Oracle JDK 1.5_0_22 and 1.6.0_21.

        Show
        Steve Rowe added a comment - I'm working on cleaning up javadoc warnings on trunk, and found a longstanding Sun javadoc bug that is hit by the javadoc on the FieldInfos no-arg constructor: /** * ... * Note: this ctor should not be used during indexing use * {@link FieldInfos#FieldInfos(FieldInfos)} or * {@link FieldInfos#FieldInfos(FieldNumberBiMap)} instead. */ Javadoc complains that it can't find the second linked-to constructor. There are two problems: first, there really is no constructor with that prototype - it should have a second parameter of type SegmentCodecsBuilder ; and second, adding the SegmentCodecsBuilder parameter doesn't make the warning go away, because of this bug: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=4464323 . Spelling out the SegmentCodecsBuilder parameter's full package works around this bug under both Oracle JDK 1.5_0_22 and 1.6.0_21.
        Hide
        Steve Rowe added a comment -

        This patch eliminates javadoc warnings on trunk under Sun JDK 1.5.0_22 and 1.6.0_21 for Lucene, and for just 1.6.0_21 on Solr.

        Show
        Steve Rowe added a comment - This patch eliminates javadoc warnings on trunk under Sun JDK 1.5.0_22 and 1.6.0_21 for Lucene, and for just 1.6.0_21 on Solr.
        Hide
        Steve Rowe added a comment -

        This patch eliminates javadoc warnings on trunk under Sun JDK 1.5.0_22 and 1.6.0_21 for Lucene, and for just 1.6.0_21 on Solr.

        Committed:

        • r1087319: trunk
        • r1087329: branch_3x

        On branch_3x, under both Sun JDK 1.5.0_22 and 1.6.0_21, there are no javadoc warnings for either Solr or Lucene.

        Show
        Steve Rowe added a comment - This patch eliminates javadoc warnings on trunk under Sun JDK 1.5.0_22 and 1.6.0_21 for Lucene, and for just 1.6.0_21 on Solr. Committed: r1087319: trunk r1087329: branch_3x On branch_3x, under both Sun JDK 1.5.0_22 and 1.6.0_21, there are no javadoc warnings for either Solr or Lucene.
        Hide
        Grant Ingersoll added a comment -

        Here's the patch I just committed.

        Show
        Grant Ingersoll added a comment - Here's the patch I just committed.
        Hide
        Steve Rowe added a comment -

        Patch annihilating modules/ javadoc warnings (in analysis/icu/ and benchmark/).

        Committing shortly.

        Show
        Steve Rowe added a comment - Patch annihilating modules/ javadoc warnings (in analysis/icu/ and benchmark/). Committing shortly.
        Hide
        Steve Rowe added a comment -

        Patch annihilating modules/ javadoc warnings (in analysis/icu/ and benchmark/).

        Committed on trunk r1087830.

        Show
        Steve Rowe added a comment - Patch annihilating modules/ javadoc warnings (in analysis/icu/ and benchmark/). Committed on trunk r1087830.

          People

          • Assignee:
            Unassigned
            Reporter:
            Grant Ingersoll
          • Votes:
            0 Vote for this issue
            Watchers:
            0 Start watching this issue

            Dates

            • Created:
              Updated:

              Development