"Maven Site" fails so can't generate javadoc, and not available on DS website either

• Key: DIRSERVER-748
• Type: Task
• Status: Closed
• Resolution: Fixed
• Priority: Critical
• Assignee: Emmanuel Lecharny
• Reporter: Norval Hope
• Affects Version/s: 1.0

Description

"Maven site" on a virgin 1.0 branch gives this exception:

C:/src/ad_branch_1.0/shared/ldap/src/main/java/org/apache/directory/shared/ldap/
exception/LdapAuthenticationException.java:38: warning - Tag @link: reference no
t found: ResultCodeEnum.INVALIDCREDENTIALS
java.util.MissingResourceException: Can't find resource for bundle com.sun.tools
.doclets.formats.html.resources.standard, key doclet.malformed_html_link_tag
        at java.util.ResourceBundle.getObject(ResourceBundle.java:325)
        at java.util.ResourceBundle.getString(ResourceBundle.java:285)
        at com.sun.tools.doclets.internal.toolkit.util.MessageRetriever.getText(
MessageRetriever.java:114)
        at com.sun.tools.doclets.internal.toolkit.util.MessageRetriever.getText(
MessageRetriever.java:92)
        at com.sun.tools.doclets.internal.toolkit.util.MessageRetriever.getText(
MessageRetriever.java:81)
        at com.sun.tools.doclets.internal.toolkit.util.MessageRetriever.warning(
MessageRetriever.java:290)
        at com.sun.tools.doclets.formats.html.HtmlDocletWriter.redirectRelativeL
inks(HtmlDocletWriter.java:1526)
        at com.sun.tools.doclets.formats.html.HtmlDocletWriter.commentTagsToStri
ng(HtmlDocletWriter.java:1438)
        at com.sun.tools.doclets.formats.html.HtmlDocletWriter.printCommentTags(
HtmlDocletWriter.java:1397)
        at com.sun.tools.doclets.formats.html.HtmlDocletWriter.printSummaryComme
nt(HtmlDocletWriter.java:1370)
        at com.sun.tools.doclets.formats.html.HtmlDocletWriter.printSummaryComme
nt(HtmlDocletWriter.java:1366)
        at com.sun.tools.doclets.formats.html.AbstractIndexWriter.printComment(A
bstractIndexWriter.java:192)
        at com.sun.tools.doclets.formats.html.AbstractIndexWriter.printDescripti
on(AbstractIndexWriter.java:164)
        at com.sun.tools.doclets.formats.html.AbstractIndexWriter.generateConten
ts(AbstractIndexWriter.java:89)
        at com.sun.tools.doclets.formats.html.SingleIndexWriter.generateIndexFil
e(SingleIndexWriter.java:76)
        at com.sun.tools.doclets.formats.html.SingleIndexWriter.generate(SingleI
ndexWriter.java:52)
        at com.sun.tools.doclets.formats.html.HtmlDoclet.generateOtherFiles(Html
Doclet.java:103)
        at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.startGeneration
(AbstractDoclet.java:122)
        at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.start(AbstractD
oclet.java:64)
        at com.sun.tools.doclets.formats.html.HtmlDoclet.start(HtmlDoclet.java:4
2)
        at com.sun.tools.doclets.standard.Standard.start(Standard.java:23)
        at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
        at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.
java:39)
        at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAcces
sorImpl.java:25)
        at java.lang.reflect.Method.invoke(Method.java:585)
        at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:269)
        at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:143)
        at com.sun.tools.javadoc.Start.parseAndExecute(Start.java:340)
        at com.sun.tools.javadoc.Start.begin(Start.java:128)
        at com.sun.tools.javadoc.Main.execute(Main.java:41)
        at com.sun.tools.javadoc.Main.main(Main.java:31)

Fixed one instance of this problem in GracefulShutdownResponse:35 (illegal @see instead of @link in javadoc comment) but just failed again further on and can't tell which particular warning is to blame this time. Seems like a maven config problem to my untrained eye, which I'm afraid means I don't know how to approach debugging it.

Marked as "critical" as I presume it is a "must fix" prior to the 1.0 release.

Comments

[Emmanuel Lecharny]

I can fix this one easily, but this won't help a lot, because we have more than one error with javadoc generation.

We should try to do a full pass on this issue, and raise it to bug (and not improvment or task), because as ADS is embedable, we must have a working javadoc.

Btw, we badly need to reference library javadoc, thus downloading sources. Working with the library binary jars is not enough.

Somebody want to spend some time fixing this problem ?

As well as the problems with the acutal javadoc, the error causing the "maven site" to bomb seems to be:

java.util.MissingResourceException: Can't find resource for bundle com.sun.tools
.doclets.formats.html.resources.standard, key doclet.malformed_html_link_tag

which looks to me like javadoc itself failing to find one of its built-in resource .properties files. The messages output by javadoc seem to all be warnings, so I think if the resource key "doclet.malformed_html_link_tag " could be resolved then the javadoc problems themselves wouldn't be fatal. That's what I meant by it looking like the problem looking like it has something to do with maven plug-in configuration. Hence the fix might best be seen as having two stages:
    1) stop "maven site" from bombing in the presence of javadoc problems
    2) fix all the javadoc to resolve any existing problems.

[Emmanuel Lecharny]

Hmmmmm...

I think you are right, and that we should fill a Maven JIRA for this problem.

[Norval Hope]

Turns out this isn't a Maven problem but a problem in javadoc itself: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=5082928

The problem is caused because any "<a" in a javadoc comment which isn't a "<a href="...">...</a> stuffs up javadoc completely, due to a missing resource key, which hasn't been fixed despite being known for years. The problems are strings like:

 * ...
 * ... <alpha> ::= ...

in org.apache.directory.shared.ldap.util.DNUtils.

which need to be replaced by "&lt;alpha> ...".

I used the regex "\*.*<[aA][a-zA-Z0-9]" to find problematic strings in shared/ldap but needs to be done over whole project (and as I have local mods I'll need to work off a clean 1.1 build in order to submit a patch).

[Emmanuel Lecharny]

Norval, I think you are right, but it would be very kind of maven not to stop generating the javacdoc for the following files as soon as javadoc program is not happy with one file :)

[Norval Hope]

Here are patches for 1.0 and 1.1 trunk that resolve the javadoc dying issue

[Emmanuel Lecharny]

Thanks for the patches !

I have applied it on 1.0-trunks, and I also fixed all the shared/** javadoc warning. There is a _lot_ of work to do in order to have a correct javadoc ...

[Emmanuel Lecharny]

Fixed, applying Norval patch and fixing waring on trunks.