Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<p>The information on this page is user-contributed. Its accuracy is not verified by the Maven team!</p>

<h1>Tips and Surprises</h1>

<ul>
	<li> &lt;bottom&gt; tag: If you want to include html markup, embed the text in a cdata section: e.g. &lt;bottom&gt;&lt;![CDATA[Copyright 2005, &lt;a xhref=&quot; <a href="http://www.mycompany.com">http://www.mycompany.com</a>&quot;&gt;MyCompany, Inc.&lt;a&gt;]]&gt;&lt;/bottom&gt;</li>
	<li>The @see and @link tags are not handeld correctly (see issue report: <a href="http://jira.codehaus.org/browse/MJAVADOC-28">http://jira.codehaus.org/browse/MJAVADOC-28</a>)</li>
</ul>

<h1>Examples</h1>

<h2>Using a different doclet</h2>

<p> This example uses Sun's standard doclet:</p>

<p>    &lt;plugin&gt;<br />
        &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;<br />
        &lt;artifactId&gt;maven-javadoc-plugin&lt;/artifactId&gt;<br />
        &lt;configuration&gt;<br />
           &lt;doclet&gt;com.sun.tools.doclets.standard.Standard&lt;/doclet --&gt;<br />
           &lt;docletPath&gt;C:\Programm Files\Java\jdk1.5.0_05\lib\tools.jar&lt;/docletPath&gt;<br />
        &lt;/configuration&gt;<br />
    &lt;/plugin&gt;<br />
 </p>

<h2>Reporting</h2>

<p>See <a class="confluence-link" href="/display/MAVENUSER/Reporting+Plugins" data-linked-resource-id="47196" data-linked-resource-type="page" data-linked-resource-default-alias="Reporting Plugins" data-base-url="http://docs.codehaus.org">Reporting Plugins</a> for an example of configuring the Javadoc plugin in the &lt;reporting&gt; section of the pom.</p>

<h2>Linking to external Javadocs</h2>

<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
            &lt;plugin>
                &lt;artifactId>maven-javadoc-plugin&lt;/artifactId>
                &lt;configuration>
                    &lt;aggregate>true&lt;/aggregate>
                    &lt;links>
                        &lt;link>http://java.sun.com/j2se/1.4.2/docs/api&lt;/link>
                        &lt;link>http://jakarta.apache.org/commons/chain/apidocs&lt;/link>
                    &lt;/links>
                &lt;/configuration>
            &lt;/plugin>
</pre></td></tr></table>

<h2>Aggregating Javadoc jars</h2>

<p>Aggregating Javadoc for the website is described <a href="http://maven.apache.org/plugins/maven-javadoc-plugin/examples/aggregate.html">here</a>.</p>

<p>According to <a href="http://maven.apache.org/plugins/maven-javadoc-plugin/jar-mojo.html">this</a>, aggregation should also work for javadoc:jar.</p>

<p>Example taken from <a href="http://www.avajava.com/tutorials/lessons/how-do-i-generate-and-deploy-a-javadoc-jar-file-for-my-project.html">here</a>:</p>
<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
                &lt;plugin>
			&lt;groupId>org.apache.maven.plugins&lt;/groupId>
			&lt;artifactId>maven-javadoc-plugin&lt;/artifactId>
			&lt;executions>
				&lt;execution>
					&lt;id>attach-javadocs&lt;/id>
					&lt;goals>
						&lt;goal>jar&lt;/goal>
					&lt;/goals>
				&lt;/execution>
			&lt;/executions>
		&lt;/plugin>
</pre></td></tr></table>

<h2>Deploying Javadoc to a Remote Server (Windows, Putty, SCP)</h2>

<p>So you want to generate Javadoc and put it on a web server for the world (or your company) to see. You just want the Javadoc; you don't want a site. And you don't want to have to set up key pairs for authentication with your web server; you just want to SCP the files with a username and password.</p>

<p>This is possible to do but takes a bit of maneuvering. The long and short of it is that you call the site-deploy goal of the maven-site-plugin, but tell it the site root is the apidocs directory.</p>

<p>To get started, give Maven the SSH login credentials for your Javadoc web server. You do this using a &lt;server&gt; tag in your settings.xml file.</p>

<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;server>
	&lt;id>someServer&lt;/id>
	&lt;username>bob&lt;/username>
	&lt;password>12345&lt;/password>
	&lt;filePermissions>644&lt;/filePermissions>
	&lt;directoryPermissions>755&lt;/directoryPermissions>
	&lt;configuration>
		&lt;sshExecutable>plink&lt;/sshExecutable>
		&lt;scpExecutable>pscp&lt;/scpExecutable>
	&lt;/configuration>
&lt;/server>
</pre></td></tr></table>

<p>(BEGIN ASIDE: Unfortunately, the &lt;sshExecutable&gt; tag above is not properly parsed by the  2.0-beta-6 version of the maven-site-plugin. You will need to get the 2.0-beta-7-SNAPSHOT version for the remote copy to work. To do this, add the snapshot repository as</p>

<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;repository>
	&lt;id>apache.org&lt;/id>
	&lt;name>Apache Maven Snapshot Repository&lt;/name>
	&lt;url>http://people.apache.org/repo/m2-snapshot-repository&lt;/url>
	&lt;releases>
		&lt;enabled>false&lt;/enabled>
	&lt;/releases>
	&lt;snapshots>
		&lt;enabled>true&lt;/enabled>
	&lt;/snapshots>
&lt;/repository>
</pre></td></tr></table>

<p>and add the plugin dependency to your project POM file as</p>

<p>END:ASIDE)</p>

<p>You now need to configure the site plugin in your POM file. For starters, you want to generate Javadoc. To do this, set your reporting tag to</p>

<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;reporting>
	&lt;plugins>
		&lt;plugin>
			&lt;groupId>org.apache.maven.plugins&lt;/groupId>
			&lt;artifactId>maven-javadoc-plugin&lt;/artifactId>
			&lt;version>2.4&lt;/version>
		&lt;/plugin>
	&lt;/plugins>
&lt;/reporting>
</pre></td></tr></table>

<p>In your &lt;build&gt; tag, configure the site plugin to only look at the apidocs directory...</p>

<table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="xml" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6eG1sfQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;plugin>
	&lt;groupId>org.apache.maven.plugins&lt;/groupId>
	&lt;artifactId>maven-site-plugin&lt;/artifactId>
	&lt;version>2.0-beta-7-SNAPSHOT&lt;/version>
	&lt;configuration>
		&lt;inputDirectory>${project.reporting.outputDirectory}/apidocs&lt;/inputDirectory>
	&lt;/configuration>
&lt;/plugin>
</pre></td></tr></table>

<p>Finally, configure your distribution management to distribute the site to the Javadoc web server...</p>

<p>That should do it. Run</p>

<table class="wysiwyg-macro" data-macro-name="code" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
mvn site-deploy
</pre></td></tr></table>

<p>and Maven should build your site and upload the Javadoc directory to your web server. If you get an error that the host is not recognized, make sure you SSH to your web server using Putty at least once in order to establish trust between your machine and the server.</p>