Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Assorted minor FAQ edits #176

Merged
merged 4 commits into from
Dec 22, 2022
Merged

Assorted minor FAQ edits #176

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c2ef2d3
Assorted minor updates
elharo Dec 12, 2022
f93bd22
Update src/site/fml/faq.fml
michael-o Dec 12, 2022
2c368a1
Update faq.fml
elharo Dec 12, 2022
f6344c0
remove outdated FAQ entry
elharo Dec 13, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
142 changes: 9 additions & 133 deletions src/site/fml/faq.fml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,8 @@ under the License.
<question>What are the Javadoc options supported by the Maven Javadoc Plugin?</question>
<answer>
<p>
All options provided by Sun on the Javadoc homepages are wrapped in the Maven Javadoc Plugin. This
plugin supports Javadoc 1.4, 1.5 and 6.0 options. Refer you to the
All options provided by Oracle on the Javadoc homepages are wrapped in the Maven Javadoc Plugin. This
plugin supports Javadoc 1.4, 1.5 and 6.0 options. Refer to the
<a href="./apidocs/org/apache/maven/plugins/javadoc/package-summary.html">Javadoc Package Summary</a>
for more information and to the <a href="./javadoc-mojo.html">Javadoc Plugin Documentation</a>.
</p>
Expand Down Expand Up @@ -73,7 +73,7 @@ under the License.
<answer>
<p>
The Javadoc Plugin calls the Javadoc tool with
<a href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#argumentfiles">argument files</a>,
<a href="https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#argumentfiles">argument files</a>,
i.e. files called 'options', 'packages' and 'argfile' (or 'files' with Jdk &lt; 1.4):
<source><![CDATA[
javadoc.exe(or .sh) @options @packages | @argfile]]></source>
Expand Down Expand Up @@ -190,7 +190,7 @@ ${project.reporting.outputDirectory}/apidocs/javadoc.exe(or .sh) \
</p>
<p>
<b>Note</b>: If your proxy needs more JVM
<a href="http://docs.oracle.com/javase/7/docs/technotes/guides/net/properties.html">networking properties</a>
<a href="https://docs.oracle.com/javase/7/docs/technotes/guides/net/properties.html">networking properties</a>
(like NTLM), you could always add JVM options using the <i>&lt;additionalJOption/&gt;</i> parameter
in your Javadoc Plugin configuration, i.e.:
<source><![CDATA[
Expand Down Expand Up @@ -273,7 +273,7 @@ mvn deploy:deploy-file \
<p>
If you use the Javadoc report in the aggregate mode, i.e. using the <code>aggregate</code> parameter, and if the
Javadoc report does not include additional source code directories defined using the
<a href="http://mojo.codehaus.org/build-helper-maven-plugin/add-source-mojo.html">build-helper:add-source</a> goal,
<a href="https://www.mojohaus.org/build-helper-maven-plugin/add-source-mojo.html">build-helper:add-source</a> goal,
you need to use the <code>javadoc:aggregate</code> goal instead of <code>javadoc:javadoc</code> goal. Read the
<a href="examples/aggregate.html">Aggregating Javadocs for Multi-Projects</a> part for more information.
</p>
Expand All @@ -287,9 +287,9 @@ mvn deploy:deploy-file \
should correctly write references in your Javadoc, i.e.:
</p>
<ul>
<li><code>@see MyMojo</code> or <code>{@link MyMojo}</code> will <b>NOT work</b>.</li>
<li><code>@see MyMojo</code> or <code>{@link MyMojo}</code> will <strong>NOT work</strong>.</li>
<li><code>@see com.mycompany.plugin.myplugin.MyMojo</code> or <code>{@link com.mycompany.myplugin.MyMojo}</code>
will <b>work</b>.</li>
will <strong>work</strong>.</li>
</ul>
</answer>
</faq>
Expand All @@ -301,132 +301,8 @@ mvn deploy:deploy-file \
</p>
</answer>
</faq>
<faq id="On Windows with Sun JDK, why javadoc:javadoc goal blows up due to an IllegalArgumentException in sun.net.www.ParseUtil.decode()">
<question>On Windows with Sun JDK, why <i>javadoc:javadoc</i> goal blows up due to an IllegalArgumentException in <i>sun.net.www.ParseUtil.decode()</i>?</question>
<answer>
<p>
You are on Windows XP with Sun JDK 5 or JDK 6 freshly installed, and when you run <i>mvn javadoc:javadoc</i>,
you are stick by an <i>sun.net.www.ParseUtil.decode()</i> exception like this
<a href="javascript:;" onclick="toggleException( '_6219854' );" style="cursor: pointer;vertical-align:text-bottom;">one</a>.
</p>
<div id="_6219854" style="display:none">
<source><![CDATA[
...
[INFO] ------------------------------------------------------------------------
[ERROR] BUILD ERROR
[INFO] ------------------------------------------------------------------------
[INFO] An error has occurred in Javadoc report generation:Exit code: 1 - java.lang.IllegalArgumentException
at sun.net.www.ParseUtil.decode(ParseUtil.java:189)
at sun.misc.URLClassPath$FileLoader.&lt;init&gt;(URLClassPath.java:953)
at sun.misc.URLClassPath$3.run(URLClassPath.java:326)
at java.security.AccessController.doPrivileged(Native Method)
at sun.misc.URLClassPath.getLoader(URLClassPath.java:320)
at sun.misc.URLClassPath.getLoader(URLClassPath.java:297)
at sun.misc.URLClassPath.findResource(URLClassPath.java:144)
at java.net.URLClassLoader$2.run(URLClassLoader.java:362)
at java.security.AccessController.doPrivileged(Native Method)
at java.net.URLClassLoader.findResource(URLClassLoader.java:359)
at java.lang.ClassLoader.getResource(ClassLoader.java:977)
at java.lang.ClassLoader.getResourceAsStream(ClassLoader.java:1159)
at javax.xml.parsers.SecuritySupport$4.run(SecuritySupport.java:96)
at java.security.AccessController.doPrivileged(Native Method)
at javax.xml.parsers.SecuritySupport.getResourceAsStream(SecuritySupport.java:89)
at javax.xml.parsers.FactoryFinder.findJarServiceProvider(FactoryFinder.java:250)
at javax.xml.parsers.FactoryFinder.find(FactoryFinder.java:223)
at javax.xml.parsers.SAXParserFactory.newInstance(SAXParserFactory.java:128)
at com.sun.tools.doclets.internal.toolkit.builders.LayoutParser.parseXML(LayoutParser.java:72)
at com.sun.tools.doclets.internal.toolkit.builders.ClassBuilder.build(ClassBuilder.java:108)
at com.sun.tools.doclets.formats.html.HtmlDoclet.generateClassFiles(HtmlDoclet.java:155)
at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.generateClassFiles(AbstractDoclet.java:164)
at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.startGeneration(AbstractDoclet.java:106)
at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.start(AbstractDoclet.java:64)
at com.sun.tools.doclets.formats.html.HtmlDoclet.start(HtmlDoclet.java:42)
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(DelegatingMethodAccessorImpl.java:25)
at java.lang.reflect.Method.invoke(Method.java:597)
at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:215)
at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:91)
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)
com.sun.tools.doclets.internal.toolkit.util.DocletAbortException
at com.sun.tools.doclets.internal.toolkit.builders.LayoutParser.parseXML(LayoutParser.java:79)
at com.sun.tools.doclets.internal.toolkit.builders.ClassBuilder.build(ClassBuilder.java:108)
at com.sun.tools.doclets.formats.html.HtmlDoclet.generateClassFiles(HtmlDoclet.java:155)
at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.generateClassFiles(AbstractDoclet.java:164)
at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.startGeneration(AbstractDoclet.java:106)
at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.start(AbstractDoclet.java:64)
at com.sun.tools.doclets.formats.html.HtmlDoclet.start(HtmlDoclet.java:42)
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(DelegatingMethodAccessorImpl.java:25)
at java.lang.reflect.Method.invoke(Method.java:597)
at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:215)
at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:91)
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)
com.sun.tools.doclets.internal.toolkit.util.DocletAbortException
at com.sun.tools.doclets.formats.html.HtmlDoclet.generateClassFiles(HtmlDoclet.java:159)
at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.generateClassFiles(AbstractDoclet.java:164)
at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.startGeneration(AbstractDoclet.java:106)
at com.sun.tools.doclets.internal.toolkit.AbstractDoclet.start(AbstractDoclet.java:64)
at com.sun.tools.doclets.formats.html.HtmlDoclet.start(HtmlDoclet.java:42)
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(DelegatingMethodAccessorImpl.java:25)
at java.lang.reflect.Method.invoke(Method.java:597)
at com.sun.tools.javadoc.DocletInvoker.invoke(DocletInvoker.java:215)
at com.sun.tools.javadoc.DocletInvoker.start(DocletInvoker.java:91)
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)

Command line was:C:\Java\jdk1.6.0_03\jre\..\bin\javadoc.exe @options @packages
...]]></source>
</div>
<p>
Your <i>CLASSPATH</i> environement variable is probably corrupted, i.e. something like:
<source>CLASSPATH=.;C:\Java\jdk1.6.0_03\jre\lib\ext\QTJava.zip;%JAVAHOME%</source>
with <code>%JAVAHOME%</code> not a valid environment variable.
</p>
<p>
To resolve it, just reset the <i>CLASSPATH</i> environement variable, i.e.: <source>set CLASSPATH=</source>
or set a new <i>CLASSPATH</i> environement variable, i.e.:
<source>set CLASSPATH=C:\Java\jdk1.6.0_03\jre\lib\ext\QTJava.zip</source>
or fix the wrong environment variable.
</p>
<p>
Refer you to
<a href="http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6219854">http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6219854</a>
from Sun for more details.
</p>

<script language="javascript" type="text/javascript">
function toggleException( divId )
{
var div = document.getElementById( divId );
if( div.style.display == '' )
{
div.style.display = 'none';
}
else
{
div.style.display = '';
}
}
</script>
</answer>
</faq>
<faq id="What are the values of encoding, docencoding and charset parameters">
<question>What are the values of <code>&lt;encoding/&gt;</code>, <code>&lt;docencoding/&gt;</code> and <code>&lt;charset/&gt;</code> parameters?</question>
<faq id="What are the values of the encoding, docencoding, and charset parameters">
<question>What are the values of the <code>&lt;encoding/&gt;</code>, <code>&lt;docencoding/&gt;</code>, and <code>&lt;charset/&gt;</code> parameters?</question>
<answer>
<p>
By default, these parameters have the following values:
Expand Down