Maven 1.x Javadoc Plugin

javadoc:generate from CVS fails in some projects

Details

  • Type: Bug Bug
  • Status: Closed Closed
  • Priority: Major Major
  • Resolution: Won't Fix
  • Affects Version/s: 1.7
  • Fix Version/s: None
  • Component/s: None
  • Labels:
    None
  • Number of attachments :
    8

Description

I'm using javadoc-1.7 from CVS and the javadoc:warning tag fails in many of our projects. Here is an example:

maven-javadoc-plugin:report:
[javadoc] Generating Javadoc
[javadoc] Javadoc execution
[javadoc] Loading source files for package com.cpqd.util.fileconnector...
[javadoc] Loading source files for package com.cpqd.util.fileconnector.conne
ctor...
[javadoc] Loading source files for package XXXX
[javadoc] Constructing Javadoc information...
[javadoc] Copying file C:\Documents and Settings\t_fl01\.maven\cache\maven-javadoc-plugin-1.7-SNAPSHOT\plugin-resources\stylesheet.css to file S:\components\components\fileconnector\target\docs\apidocs\stylesheet.css...
[javadoc] Building tree for all the packages and classes...
[javadoc] Building index for all the packages and classes...
[javadoc] javadoc: warning - getUserName: @return tag has no arguments.
[javadoc] Building index for all classes...
[javadoc] Generating S:\components\components\fileconnector\target\docs\apidocs\help-doc.html...
[javadoc] 1 warning

BUILD FAILED
File...... C:\Documents and Settings\t_fl01\.maven\cache\maven-javadoc-plugin-1.7-SNAPSHOT\plugin.jelly
Element... javadoc:javadocwarnings
Line...... 483
Column.... 11
String index out of range: -1
Total time: 13 seconds
Finished at: Wed Sep 01 17:42:13 BRT 2004

I will see if I can narrow down the issue and realize what's going on.
I guess the javadoc is generating some output in an unexpected format that crashes the parser (i.e, the JavadocWarningsTextToXml.java) - if that's the case, I think it would be safer to ignore such exceptions, at least while this new feature is not stable yet (as we might face some similar issues in the future as the users uses other JDKs or javadoclets to generate the output).

Attachments

  1. File
    javadocwarnings.diff
    09/Jan/05 12:28 PM
    20 kB
    Steven Caswell
  2. File
    javadoc-warnings-13.jsl
    09/Jan/05 12:31 PM
    3 kB
    Steven Caswell
  3. Text File
    report-13.txt
    28/Dec/04 3:04 PM
    2 kB
    Arnaud Heritier
  4. Text File
    report-14.txt
    28/Dec/04 3:01 PM
    4 kB
    Arnaud Heritier
  5. Text File
    report-15.txt
    28/Dec/04 3:08 PM
    3 kB
    Arnaud Heritier
  6. Java Source File
    StandardDoclet13XmlBuilder.java
    09/Jan/05 12:30 PM
    2 kB
    Steven Caswell
  7. Java Source File
    StandardDocletDefaultXmlBuilder.java
    09/Jan/05 12:31 PM
    5 kB
    Steven Caswell
  8. Java Source File
    XmlBuilder.java
    09/Jan/05 12:29 PM
    1 kB
    Steven Caswell

Issue Links

This issue is depended upon by:
MPJAVADOC-35 Add javadoc warning report formatted similar to Checkstyle report Minor Closed

Activity

Ascending order - Click to sort in descending order
Hide
Permalink
Arnaud Heritier added a comment -

+1 for me Felipe. The plugin mustn't fail if there's a problem with the warnings report.

Show
Arnaud Heritier added a comment - +1 for me Felipe. The plugin mustn't fail if there's a problem with the warnings report.
Hide
Permalink
Felipe Leme added a comment -

Ok, I fixed the code to ignore the exception. Now I've found the issue:

On JDK 1.4, javadoc prints the file and number that raised the issue:

[javadoc] /home/felipeal/cvs/maven/maven-plugins/javadoc/src/plugin-test/test08/target/javadoc/src/org/apache/maven/Dummy.java:10: warning - @return tag has no arguments.

On JDK 1.3, it doesn't:

[javadoc] javadoc: warning - getUserName: @return tag has no arguments.

Now that we know the issue, we have 2 options:

1.Calculate where the warning is and generate a different report entry if the file/line info is not there
2.Disable the report when running JDK 1.3, as it might be useless without that info

So, what do you think?

Show
Felipe Leme added a comment - Ok, I fixed the code to ignore the exception. Now I've found the issue: On JDK 1.4, javadoc prints the file and number that raised the issue: [javadoc] /home/felipeal/cvs/maven/maven-plugins/javadoc/src/plugin-test/test08/target/javadoc/src/org/apache/maven/Dummy.java:10: warning - @return tag has no arguments. On JDK 1.3, it doesn't: [javadoc] javadoc: warning - getUserName: @return tag has no arguments. Now that we know the issue, we have 2 options: 1.Calculate where the warning is and generate a different report entry if the file/line info is not there 2.Disable the report when running JDK 1.3, as it might be useless without that info So, what do you think?
Hide
Permalink
Felipe Leme added a comment -

Steven,

The JavadocWarningsTextToXml.buildMap() method is throwing a exception when building the javadoc with JDK 1.3.

So, could you please take a look on MPJAVADOC-42?

Thanks,

Felipe

Show
Felipe Leme added a comment - Steven, The JavadocWarningsTextToXml.buildMap() method is throwing a exception when building the javadoc with JDK 1.3. So, could you please take a look on MPJAVADOC-42? Thanks, Felipe
Hide
Permalink
Felipe Leme added a comment -

Changing priority as this is not a bug anymore (if the author doesn't send a new patch, I will try to fix it myself after the 1.0.1 timeframe)

Show
Felipe Leme added a comment - Changing priority as this is not a bug anymore (if the author doesn't send a new patch, I will try to fix it myself after the 1.0.1 timeframe)
Hide
Permalink
Steven Caswell added a comment -

Sorry to have taken so long to respond.

I don't have access to a 1.3 system, so if someone could attach the text version of the javadoc report, I'll be happy to make the mods to fix the issue.

I think the report would still be useful without the line numbers, if only for readability.

Show
Steven Caswell added a comment - Sorry to have taken so long to respond. I don't have access to a 1.3 system, so if someone could attach the text version of the javadoc report, I'll be happy to make the mods to fix the issue. I think the report would still be useful without the line numbers, if only for readability.
Hide
Permalink
Arnaud Heritier added a comment -

report generated for the test 06 (maven-plugins\javadoc\src\plugin-test\test06) with a jdk 1.4

Show
Arnaud Heritier added a comment - report generated for the test 06 (maven-plugins\javadoc\src\plugin-test\test06) with a jdk 1.4
Hide
Permalink
Arnaud Heritier added a comment -

report generated for the test 06 (maven-plugins\javadoc\src\plugin-test\test06) with a jdk 1.3

Show
Arnaud Heritier added a comment - report generated for the test 06 (maven-plugins\javadoc\src\plugin-test\test06) with a jdk 1.3
Hide
Permalink
Arnaud Heritier added a comment -

report generated for the test 06 (maven-plugins\javadoc\src\plugin-test\test06) with a jdk 1.5

Show
Arnaud Heritier added a comment - report generated for the test 06 (maven-plugins\javadoc\src\plugin-test\test06) with a jdk 1.5
Hide
Permalink
Arnaud Heritier added a comment -

Steven, I follow your opinion.
I think that the line number is useful but not mandatory.

Show
Arnaud Heritier added a comment - Steven, I follow your opinion. I think that the line number is useful but not mandatory.
Hide
Permalink
Steven Caswell added a comment -

I've made changes to fix the issue. To summarize, I refactored JavadocWarningsTextToXml code to parse the warnings text and build the xml into separate strategies, one for the standard doclet 1.3 and one for the standard doclet 1.4/1.5. To tell the JavadocWarningsTextToXml code which strategy to use, I added a doclet type property that is set by the plugin.jelly script.

I added a plugin property maven.javadoc.warnings.docletType to specify which strategy to use. Because the xml generated for the 1.3 doclet doesn't contain files or line numbers, I created a different jelly stylesheet to handle the 1.3 warnings.

Diff and new file attachments to follow.

Show
Steven Caswell added a comment - I've made changes to fix the issue. To summarize, I refactored JavadocWarningsTextToXml code to parse the warnings text and build the xml into separate strategies, one for the standard doclet 1.3 and one for the standard doclet 1.4/1.5. To tell the JavadocWarningsTextToXml code which strategy to use, I added a doclet type property that is set by the plugin.jelly script. I added a plugin property maven.javadoc.warnings.docletType to specify which strategy to use. Because the xml generated for the 1.3 doclet doesn't contain files or line numbers, I created a different jelly stylesheet to handle the 1.3 warnings. Diff and new file attachments to follow.
Hide
Permalink
Steven Caswell added a comment -

Changes to support generating javadoc warnings under 1.3:

src/main/org.apache.maven.javadoc/JavadocWarningsTextToXml.java:

  • Refactored methods that parse the text and generate the XML into seperate strategies, one for the 1.3 doclet and one for the 1.4/1.5 doclet.
  • Added a doclet type property that tells the class which strategy to use, to be set by plugin.jelly

src/test/org/apache/maven/javadoc/JavadocWarningsTextToXmlTest.java:

  • Added tests for the new 1.3 doclet handling

plugin.properties:

  • Added maven.javadoc.warnings.docletType to define to specify which doclet handling strategy to use.

plugin.jelly:

  • Added setting the doclet type property of the javadoc warnings bean to the value of the maven.javadoc.warnings.docletType
  • Added determining the jsl stylesheet based on the value of the maven.javadoc.warnings.docletType
Show
Steven Caswell added a comment - Changes to support generating javadoc warnings under 1.3: src/main/org.apache.maven.javadoc/JavadocWarningsTextToXml.java:
  • Refactored methods that parse the text and generate the XML into seperate strategies, one for the 1.3 doclet and one for the 1.4/1.5 doclet.
  • Added a doclet type property that tells the class which strategy to use, to be set by plugin.jelly
src/test/org/apache/maven/javadoc/JavadocWarningsTextToXmlTest.java:
  • Added tests for the new 1.3 doclet handling
plugin.properties:
  • Added maven.javadoc.warnings.docletType to define to specify which doclet handling strategy to use.
plugin.jelly:
  • Added setting the doclet type property of the javadoc warnings bean to the value of the maven.javadoc.warnings.docletType
  • Added determining the jsl stylesheet based on the value of the maven.javadoc.warnings.docletType
Hide
Permalink
Steven Caswell added a comment -

src/main/org.apache.maven.javadoc/XmlBuilder.java:

  • Interface for the strategy
Show
Steven Caswell added a comment - src/main/org.apache.maven.javadoc/XmlBuilder.java:
  • Interface for the strategy
Hide
Permalink
Steven Caswell added a comment -

src/main/org/apache/maven/javadoc/StandardDoclet13XmlBuilder.java:

  • Implemenation of XmlBuilder strategy to handle javadoc warnings from the 1.3 standard doclet
Show
Steven Caswell added a comment - src/main/org/apache/maven/javadoc/StandardDoclet13XmlBuilder.java:
  • Implemenation of XmlBuilder strategy to handle javadoc warnings from the 1.3 standard doclet
Hide
Permalink
Steven Caswell added a comment -

src/main/org/apache/maven/javadoc/StandardDocletDefaultXmlBuilder.java:

  • Implemenation of XmlBuilder strategy to handle javadoc warnings from the 1.4/1.5 standard doclet
Show
Steven Caswell added a comment - src/main/org/apache/maven/javadoc/StandardDocletDefaultXmlBuilder.java:
  • Implemenation of XmlBuilder strategy to handle javadoc warnings from the 1.4/1.5 standard doclet
Hide
Permalink
Steven Caswell added a comment -

src/plugin-resources/javadoc-warnings-13.jsl:

  • Created from javadoc-warnings.jsl to handle outputing of the 1.3 style warnings
Show
Steven Caswell added a comment - src/plugin-resources/javadoc-warnings-13.jsl:
  • Created from javadoc-warnings.jsl to handle outputing of the 1.3 style warnings
Hide
Permalink
Steven Caswell added a comment -

The test case (src/test/org/apache/maven/javadoc/JavadocWarningsTextToXmlTest.java) requires the files report-13.txt, report-14.txt, and report-15.txt to reside in src/test

The one thing I don't know how to do is to set up a test case to test plugin jelly under the different jdks.

Show
Steven Caswell added a comment - The test case (src/test/org/apache/maven/javadoc/JavadocWarningsTextToXmlTest.java) requires the files report-13.txt, report-14.txt, and report-15.txt to reside in src/test The one thing I don't know how to do is to set up a test case to test plugin jelly under the different jdks.
Hide
Permalink
Felipe Leme added a comment -

I'm unassigning it as I'm really out of spare time lately.

Anyway, regarding the last post, I don't know the answer either. Maybe the best solution is to write a test case for JDK 1.3 and put a <j:if> call in the beginning of the test checking for the JDK version and skipping the test if the version is not 1.3

Show
Felipe Leme added a comment - I'm unassigning it as I'm really out of spare time lately. Anyway, regarding the last post, I don't know the answer either. Maybe the best solution is to write a test case for JDK 1.3 and put a <j:if> call in the beginning of the test checking for the JDK version and skipping the test if the version is not 1.3
Hide
Permalink
Lukas Theussl added a comment -

Closing as won't fix as maven 1.1 will require jdk >= 1.4.

Show
Lukas Theussl added a comment - Closing as won't fix as maven 1.1 will require jdk >= 1.4.

People

Vote (1)
Watch (1)

Dates

  • Created:
    Updated:
    Resolved:

Time Tracking

Estimated:
3h
Original Estimate - 3 hours
Remaining:
2h 20m
Time Spent - 40 minutes Remaining Estimate - 2 hours, 20 minutes
Logged:
40m
Time Spent - 40 minutes Remaining Estimate - 2 hours, 20 minutes
Atlassian JIRA (v4.4.3#663-r165197) | Report a problem
Powered by a free Atlassian JIRA open source license for Codehaus. Try JIRA - bug tracking software for your team.