Uploaded image for project: 'Lucene - Core'
  1. Lucene - Core
  2. LUCENE-875

javadocs creation has too many warnings/errors

    Details

    • Type: Task
    • Status: Closed
    • Priority: Minor
    • Resolution: Fixed
    • Affects Version/s: 2.2
    • Fix Version/s: 2.2
    • Component/s: general/javadocs
    • Labels:
      None
    • Lucene Fields:
      Patch Available

      Description

      Currently running 'ant javadocs' creates so many warnings that you have to grep the output to verify that new code did not add more.

      While most current errors might be minor, they might hide a few serious ones that we will never know abut until someone complains.

      Best if we fix all of them and keep it always clean...

      1. 875_javacc_patch.txt
        23 kB
        Doron Cohen
      2. 875_javacc_patch.txt
        22 kB
        Doron Cohen
      3. 875_javacc_patch.txt
        21 kB
        Doron Cohen

        Issue Links

          Activity

          Hide
          doronc Doron Cohen added a comment -

          ( modified 'and javadocs' --> 'ant javadocs' )

          Show
          doronc Doron Cohen added a comment - ( modified 'and javadocs' --> 'ant javadocs' )
          Hide
          doronc Doron Cohen added a comment -

          Attached patch fixes all javadocs warnings and errors when using javadocs 1.4.2.

          javadocs with jdk 5 - current build.xml creates javadocs also for contrib/gdata only
          under jdk 5. To fix the javadocs some jars had to be added to the javadocs classpath.
          But for gdata, even after adding the required jars there remained lots of errors that I
          did not want to handle here. So I commented out the addition of gdata jars, and focused
          in running javadocs with jdk 1.4.2.

          Some of the warning had to do with peculiarities of javadocs, In one case I replaced '?'
          with '?' - wasn't too happy with this, but it seemed nice at that particular code
          to have the '?' at the middle of a summary line, which was causing the warning. (in
          other places I changed the wording so that '?' was o more in the summary line).

          This is quite a technical fix - only javadoc comments where modified (and build.xml), so unless
          there are objections I intend to commit it pretty soon.

          Show
          doronc Doron Cohen added a comment - Attached patch fixes all javadocs warnings and errors when using javadocs 1.4.2. javadocs with jdk 5 - current build.xml creates javadocs also for contrib/gdata only under jdk 5. To fix the javadocs some jars had to be added to the javadocs classpath. But for gdata, even after adding the required jars there remained lots of errors that I did not want to handle here. So I commented out the addition of gdata jars, and focused in running javadocs with jdk 1.4.2. Some of the warning had to do with peculiarities of javadocs, In one case I replaced '?' with '?' - wasn't too happy with this, but it seemed nice at that particular code to have the '?' at the middle of a summary line, which was causing the warning. (in other places I changed the wording so that '?' was o more in the summary line). This is quite a technical fix - only javadoc comments where modified (and build.xml), so unless there are objections I intend to commit it pretty soon.
          Hide
          hossman Hoss Man added a comment -

          skimmed the patch, noticed isPayloadAvailable method added to MemoryIndex .. unintentional?

          Show
          hossman Hoss Man added a comment - skimmed the patch, noticed isPayloadAvailable method added to MemoryIndex .. unintentional?
          Hide
          doronc Doron Cohen added a comment -

          yes... thanks for reviewing this Hoss.

          MemoryIndex doesn't compile without implementing this method.
          But this is unrelated to the javadocs, so I will not include in this change.

          Show
          doronc Doron Cohen added a comment - yes... thanks for reviewing this Hoss. MemoryIndex doesn't compile without implementing this method. But this is unrelated to the javadocs, so I will not include in this change.
          Hide
          hossman Hoss Man added a comment -

          i vote for adding...

          failonerror="true"

          ...as well. it won't help in the case of warnings, but it will at least ensure that the build fails if we have any seriously eggregious errors in the javadocs that completely prevent them from being generated.

          Show
          hossman Hoss Man added a comment - i vote for adding... failonerror="true" ...as well. it won't help in the case of warnings, but it will at least ensure that the build fails if we have any seriously eggregious errors in the javadocs that completely prevent them from being generated.
          Hide
          doronc Doron Cohen added a comment -

          Agree, I will add that.

          Show
          doronc Doron Cohen added a comment - Agree, I will add that.
          Hide
          doronc Doron Cohen added a comment -

          > it won't help in the case of warnings

          We could make it fail also in case of warnings: logging javadoc stdio also to file; fail if the file has warnings (otherwise delete file);

          Show
          doronc Doron Cohen added a comment - > it won't help in the case of warnings We could make it fail also in case of warnings: logging javadoc stdio also to file; fail if the file has warnings (otherwise delete file);
          Hide
          doronc Doron Cohen added a comment -

          An updated patch:

          • without the MemoryIndex changes (was fixed separately).
          • failonerror=true added as Hoss suggested.
          • now fails also on javadoc warnings, as discussed above.
          Show
          doronc Doron Cohen added a comment - An updated patch: without the MemoryIndex changes (was fixed separately). failonerror=true added as Hoss suggested. now fails also on javadoc warnings, as discussed above.
          Hide
          doronc Doron Cohen added a comment -

          It occurred to me that with this, javadoc with jdk 1.5, which also processes gdata, would fail on errors. Ucommenting the gdata-jars addition to javadocs-classpath would solve the errors but there are many warnings still. Then, the fail-on-warning logic would cause javadoc to fail.

          By itself this is not necessarily a bad thing, as it would encourage to fix that sooner. However when invoked as part of a larger target, like "package" or "nightly", it would stop that target in the middle.

          Show
          doronc Doron Cohen added a comment - It occurred to me that with this, javadoc with jdk 1.5, which also processes gdata, would fail on errors. Ucommenting the gdata-jars addition to javadocs-classpath would solve the errors but there are many warnings still. Then, the fail-on-warning logic would cause javadoc to fail. By itself this is not necessarily a bad thing, as it would encourage to fix that sooner. However when invoked as part of a larger target, like "package" or "nightly", it would stop that target in the middle.
          Hide
          hossman Hoss Man added a comment -

          huh ... i've never seen the <record> task before ... interesting.

          not being familiar with it, i don't really have an opinion about using it it in this way, but the gdata situation is ... annoying. we may want to hold off on failing on warnings until we can get them all squared away (and/or have a better system in place for dealing with contribs that require 1.5)

          Show
          hossman Hoss Man added a comment - huh ... i've never seen the <record> task before ... interesting. not being familiar with it, i don't really have an opinion about using it it in this way, but the gdata situation is ... annoying. we may want to hold off on failing on warnings until we can get them all squared away (and/or have a better system in place for dealing with contribs that require 1.5)
          Hide
          doronc Doron Cohen added a comment -

          Agree.
          I am changing it to fail-on-warning only under 1.4, with TODO comment to remove this condition once gdata javadocs is fixed.
          I intend to commit this and create a new issue for gdata's javadoc warnings.

          Show
          doronc Doron Cohen added a comment - Agree. I am changing it to fail-on-warning only under 1.4, with TODO comment to remove this condition once gdata javadocs is fixed. I intend to commit this and create a new issue for gdata's javadoc warnings.
          Hide
          doronc Doron Cohen added a comment -

          Updated patch:
          1) as discussed, disable fail-on-warning under jdk5.
          2) updated Changes.txt

          Show
          doronc Doron Cohen added a comment - Updated patch: 1) as discussed, disable fail-on-warning under jdk5. 2) updated Changes.txt
          Hide
          doronc Doron Cohen added a comment -

          Just committed.

          Show
          doronc Doron Cohen added a comment - Just committed.
          Hide
          hossman Hoss Man added a comment -

          Grrr... it seems we may need to reopen this, i didn't realize until just now that the previous patch (including "fail on warnings unless 1.4" was already committed) and my recent tweak to the build.xml so that all contribs get their javadocs built has spanwed some more warnings/problems that i didn't notice before because i was using 1.5 (and apparently so is hudson because the nightly build is still working).

          Note, if you are using java 1.5 and wnat to reproduce these problems, use...
          ant -Dant.java.version=1.4 javadocs

          Current issues:

          1) running javadocs on a virgin checkout does not force contribs that download their dependencies on the fly to do so – the javadocs task currently has no dependencies that relate to contribs, so "ant javadocs" or even "ant package" will get errors from things like contrib/db because the sleepycat jar has never been downloaded.
          (NOTE: you can NOT reproduce this by running "ant clean javadocs" ... the clean target doesn't remove lib jars that contribs download on the fly .. if you've ever build contribs you've got the jars and it will mask this bug)

          Possible solution: make "javadocs" depend on build-contrib ? or a new task that does the contrib-crawl and calls whatever task contribs use to fetch third party jars?

          2) even if all the jars are downloaded, and running in 1.4 mode so current gdata errors are ignored, there are still 3 warnings...

          [javadoc] javadoc: warning - Multiple sources of package comments found for package "org.apache"
          [javadoc] javadoc: warning - Multiple sources of package comments found for package "org"
          [javadoc] javadoc: warning - Multiple sources of package comments found for package "org.apache.commons"

          ...my first guess is that multiple lib jars in the contribs had package.html files for these packages ... but i can't find evidence of that ... i haven't tried the trial and error approach of commenting out contribs one at a time until those errors go away to try and track down the source of the problem

          3) Hudson seems to be running the nightly build using java 1.5, so the hook to ensure that there are no javadoc warnings isn't getting triggered.

          Show
          hossman Hoss Man added a comment - Grrr... it seems we may need to reopen this, i didn't realize until just now that the previous patch (including "fail on warnings unless 1.4" was already committed) and my recent tweak to the build.xml so that all contribs get their javadocs built has spanwed some more warnings/problems that i didn't notice before because i was using 1.5 (and apparently so is hudson because the nightly build is still working). Note, if you are using java 1.5 and wnat to reproduce these problems, use... ant -Dant.java.version=1.4 javadocs Current issues: 1) running javadocs on a virgin checkout does not force contribs that download their dependencies on the fly to do so – the javadocs task currently has no dependencies that relate to contribs, so "ant javadocs" or even "ant package" will get errors from things like contrib/db because the sleepycat jar has never been downloaded. (NOTE: you can NOT reproduce this by running "ant clean javadocs" ... the clean target doesn't remove lib jars that contribs download on the fly .. if you've ever build contribs you've got the jars and it will mask this bug) Possible solution: make "javadocs" depend on build-contrib ? or a new task that does the contrib-crawl and calls whatever task contribs use to fetch third party jars? 2) even if all the jars are downloaded, and running in 1.4 mode so current gdata errors are ignored, there are still 3 warnings... [javadoc] javadoc: warning - Multiple sources of package comments found for package "org.apache" [javadoc] javadoc: warning - Multiple sources of package comments found for package "org" [javadoc] javadoc: warning - Multiple sources of package comments found for package "org.apache.commons" ...my first guess is that multiple lib jars in the contribs had package.html files for these packages ... but i can't find evidence of that ... i haven't tried the trial and error approach of commenting out contribs one at a time until those errors go away to try and track down the source of the problem 3) Hudson seems to be running the nightly build using java 1.5, so the hook to ensure that there are no javadoc warnings isn't getting triggered.
          Hide
          doronc Doron Cohen added a comment -

          I checked with 1.4 earlier today and didn't get these "Multiple sources" warnings.
          I checked again now, also with 1.5 and -Dant.java.version=1.4 and it passes as well.
          This was Windows: Standard Doclet version 1.5.0_06 and Standard Doclet version 1.4.2_08
          So I don't know what is causing these errors.
          Seems ok to have "javadocs" depend on "build-contrib".
          Should we disable this fail-on-warning logic until clearing it further...?

          Show
          doronc Doron Cohen added a comment - I checked with 1.4 earlier today and didn't get these "Multiple sources" warnings. I checked again now, also with 1.5 and -Dant.java.version=1.4 and it passes as well. This was Windows: Standard Doclet version 1.5.0_06 and Standard Doclet version 1.4.2_08 So I don't know what is causing these errors. Seems ok to have "javadocs" depend on "build-contrib". Should we disable this fail-on-warning logic until clearing it further...?
          Hide
          doronc Doron Cohen added a comment -

          Also, since failOnEror was added to the javadocs task, build services (e.g. parabuild) with jars misconfigured would fail not only because of javadoc warnings but also because of javadoc errors.

          I feel that the noise this created with the failures of builds due to javadocs problems is a price to high to pay for being automatically "forced" to keep javadocs error/warning free. I am disabling both fail-on-jdoc-error and fail-on-jdoc-warning.

          I will add an item "check javadocs creation" to Wiki's "Patch Check List" page.

          Show
          doronc Doron Cohen added a comment - Also, since failOnEror was added to the javadocs task, build services (e.g. parabuild) with jars misconfigured would fail not only because of javadoc warnings but also because of javadoc errors. I feel that the noise this created with the failures of builds due to javadocs problems is a price to high to pay for being automatically "forced" to keep javadocs error/warning free. I am disabling both fail-on-jdoc-error and fail-on-jdoc-warning. I will add an item "check javadocs creation" to Wiki's "Patch Check List" page.
          Hide
          doronc Doron Cohen added a comment -

          I also made "javadocs" depend on "build-contrib".

          This too might create some noise, because when attempting to download jars from the net, some firewall prompt might pop up. If running unattended and no one approves, it might eventually time out and fail. On the other hand, we do want the jars to be downloaded... So let's wait a few days and see how this works out.

          Show
          doronc Doron Cohen added a comment - I also made "javadocs" depend on "build-contrib". This too might create some noise, because when attempting to download jars from the net, some firewall prompt might pop up. If running unattended and no one approves, it might eventually time out and fail. On the other hand, we do want the jars to be downloaded... So let's wait a few days and see how this works out.
          Hide
          hossman Hoss Man added a comment -

          I'm not sure i follow why failOnError concerns you ... but in general i think you're right ... Lucene's build system just isn't quite "clean" enough at the moment to be so critical of javadoc issues.

          as for the "Multiple sources of package comments" i'm using "Standard Doclet version 1.5.0_02" FWIW.

          Show
          hossman Hoss Man added a comment - I'm not sure i follow why failOnError concerns you ... but in general i think you're right ... Lucene's build system just isn't quite "clean" enough at the moment to be so critical of javadoc issues. as for the "Multiple sources of package comments" i'm using "Standard Doclet version 1.5.0_02" FWIW.
          Hide
          doronc Doron Cohen added a comment -

          Fixed - we remain with not failing a build due to javadoc warnings or errors - verifying these would remain manual.

          Show
          doronc Doron Cohen added a comment - Fixed - we remain with not failing a build due to javadoc warnings or errors - verifying these would remain manual.

            People

            • Assignee:
              doronc Doron Cohen
              Reporter:
              doronc Doron Cohen
            • Votes:
              1 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development