Javadoc fails with illegal package name using footer or bottom tags. The problem seems to be that in the class Javadoc the footer and the bottom html content is added untrimmed and unescaped. See org.apache.tools.ant.taskdefs.Javadoc.execute(){ ... if (footer != null) { toExecute.createArgument().setValue("-footer"); toExecute.createArgument().setValue(expand(footer.getText())); } ...} The text returned by footer.getText() has leading newline and tab characters, which will be interpreted by the javadoc command as package declarations. These newline and tab characters are not specified in our build.xml, so these characters seems to be added after the call while processing the javadoc task.
Here the javadoc task: <javadoc destdir="${javadoc.temp.dir}" packagenames="${javadoc.packages}" excludepackagenames="" useexternalfile="yes" verbose="on" author="true" version="true" use="false" public="true" source="1.5" windowtitle="AWindowTitle" doctitle="ADocTile" stylesheetfile="${javadoc.styling.dir}/javadoc.css"> <classpath refid="${custom-compile-classpath}" /> <bottom><![CDATA[<table border=0 cellpadding=0><tr><td><img src="{@docRoot}/icon.gif" width="32"></td><td>Copyright © ${copyright.year} demo company. All rights reserved.</td></tr></table>]]></bottom> <packageset dir="${javadoc.sources.dir}" defaultexcludes="yes"> <include name="**"/> <exclude name="**/doc-files/**"/> </packageset> </javadoc>
Created attachment 22668 [details] Escapes line breaks in javadoc arguments file This is a patch for 1.7.1 that escapes any line breaks that are found in any of the arguments written out to a javadoc options file.
Created attachment 22669 [details] Escapes new lines in javadoc arguments This is the same a patch #22668 except that it was created against the trunk version of the javadoc task.
Is escaping the newlines really necessary? http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#argumentfiles contains under "Example - Option Arguments" a -bottom example that seems to indicate that quoting the entire argument should be enough. The Java6 docs contains the same example but explicitly mentions the need to double backslashes when quoting in the initial paragraph (the 1.4.2 docs miss that).
Yes, unfortunately, they are necessary. The original reporter's <bottom> text will work now--I think the 1.7.0 code somehow inserted a line break, but it's been a long time since I looked at it. This bug kept us from upgrading at the time since our <bottom> text has line breaks in it and there wasn't a workaround. Now, there's a workaround for us--remove all line breaks. Since it looked like an easy fix, I decided to go ahead and submit the patch instead of removing the breaks in our build file--kind of a pain without them.
thanks for the patch, I've committed a slightly different version (avoid escaping the \n in a \r\n sequence) with svn revision 703516 - and added a test as well. This doesn't fix the userexternalfile="false" case, I guess. Buth then again, that cannot work anyway. I've documented that.
Thanks, Stefan. I'd tested the double escape case and found that it didn't cause a problem. Avoiding it is a better choice, however.