Skip to content

Commit

Permalink
Assorted minor FAQ edits (#176)
Browse files Browse the repository at this point in the history 
* Assorted minor updates

Sun --> Oracle
Update some URLs

* Update src/site/fml/faq.fml

Co-authored-by: Piotrek Żygieło <11896137+pzygielo@users.noreply.github.com>

* Update faq.fml

* remove outdated FAQ entry

Co-authored-by: Michael Osipov <michaelo@apache.org>
Co-authored-by: Piotrek Żygieło <11896137+pzygielo@users.noreply.github.com>
  • Loading branch information
@elharo @michael-o @pzygielo
3 people committed Dec 22, 2022
1 parent 73557e3 commit a654cc6
Showing 1 changed file with 9 additions and 133 deletions.
142 changes: 9 additions & 133 deletions src/site/fml/faq.fml
View file
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

0 comments on commit a654cc6

Please sign in to comment.