Search code examples
javajavadocmaven-javadoc-plugin

Javadoc warning being shown while generating the package

I'm working on the javadocs of a project, fixing all the errors and warnings that Javadoc shows.. But after fixing most of them, there are just this one that is being shown for some reason that I can't imagine.

4 warnings
[WARNING] Javadoc Warnings
[WARNING] C:\Users\magno\Documents\Globalmentor\Globalmentor's work\marmot\src\main\java\com\globalmentor\marmot\MarmotSession.java:100: warning - Tag @see: can't find getResourceKit(Repository, URFResource, Capability...) in com.globalmentor.marmot.MarmotSession
[WARNING] C:\Users\magno\Documents\Globalmentor\Globalmentor's work\marmot\src\main\java\com\globalmentor\marmot\MarmotSession.java:140: warning - Tag @see: can't find getResourceKit(Repository, URFResource, Capability...) in com.globalmentor.marmot.MarmotSession
[WARNING] C:\Users\magno\Documents\Globalmentor\Globalmentor's work\marmot\src\main\java\com\globalmentor\marmot\MarmotSession.java:166: warning - Tag @link: can't find getResourceKit(Repository, URFResource, Capability...) in com.globalmentor.marmot.MarmotSession
[WARNING] C:\Users\magno\Documents\Globalmentor\Globalmentor's work\marmot\src\main\java\com\globalmentor\marmot\MarmotSession.java:140: warning - Tag @link: can't find getResourceKit(Repository, URFResource, Capability...) in com.globalmentor.marmot.MarmotSession
[INFO] Building jar: C:\Users\magno\Documents\Globalmentor\Globalmentor's work\marmot\target\marmot-0.5.1-SNAPSHOT-javadoc.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 33.921 s
[INFO] Finished at: 2016-10-21T10:03:11-02:00
[INFO] Final Memory: 29M/412M
[INFO] ------------------------------------------------------------------------

The problem is: These references are on the same class than the method, and even Eclipse suggests them when I start writing the references, does anybody know anything else that could give me this warning?

Here is the javadocs that shows the warning:

/**
 * Determines if there exists resource kit appropriate for the given resource supporting the given capabilities.
 * @param repository The repository in which the resource resides.
 * @param resource The resource for which a resource kit should be returned.
 * @param capabilities The capabilities required for the resource kit.
 * @return <code>true</code> if there exists a resource kit to handle the given resource with the given capabilities, if any, in relation to the resource.
 * @see #getResourceKit(Repository, URFResource, Capability...)
 */
public boolean hasResourceKit(final Repository repository, final URFResource resource, final Capability... capabilities);

/**
 * Retrieves a resource kit appropriate for the given resource statically if possible, without further resource lookup. This method locates a resource kit in
 * the following priority:
 * <p>
 * The first resource kit supporting the resource content type determined by:
 * </p>
 * <ol>
 * <li>The given content type, if any.</li>
 * <li>The content determined if possible by {@link #getExtensionContentType(String)} from the resource URI extension.</li>
 * <li>The resource description is retrieved as a last resort and the resource kit is determined by delegating to
 * {@link #getResourceKit(Repository, URFResource, Capability...)}.</li>
 * </ol>
 * @param repository The repository in which the resource resides.
 * @param resourceURI The URI of the resource in the given repository.
 * @param contentType The type of content the resource contains, or <code>null</code> if unknown.
 * @param capabilities The capabilities required for the resource kit.
 * @return A resource kit to handle the given resource with the given capabilities, if any, in relation to the resource; or <code>null</code> if there is no
 *         registered resource kit with the given capabilities in relation to the resource.
 * @throws ResourceIOException if an error occurred retrieving a description of the resource kit.
 * @see #getResourceKit(Repository, URFResource, Capability...)
 */
public RK getResourceKit(final Repository repository, final URI resourceURI, final ContentType contentType, final Capability... capabilities)
        throws ResourceIOException;

/**
 * Retrieves a resource kit appropriate for a MIME content type. This method should only be used for special-purpose functionality; when accessing resources
 * {@link #getResourceKit(Repository, URFResource, Capability...)} should normally be used instead.
 * @param contentType The type of content the resource contains.
 * @param capabilities The capabilities required for the resource kit.
 * @return A resource kit with the requested capabilities to handle the given content type, or <code>null</code> if no appropriate resource kit is registered.
 */
public RK getResourceKit(final ContentType contentType, final Capability... capabilities);

And here is the method that's being referenced in the javadocs above, it's from the same class:

/**
 * Retrieves a resource kit appropriate for the given resource. This method locates a resource kit in the following priority:
 * <ol>
 * <li>The first resource kit supporting the resource content type determined by {@link #determineContentType(URFResource)}.</li>
 * <li>The first resource kit supporting one of the resource types.</li>
 * <li>If the resource has a collection URI, the default collection resource kit.</li>
 * <li>The default resource kit.</li>
 * </ol>
 * @param repository The repository in which the resource resides.
 * @param resource The resource for which a resource kit should be returned.
 * @param capabilities The capabilities required for the resource kit.
 * @return A resource kit to handle the given resource with the given capabilities, if any, in relation to the resource; or <code>null</code> if there is no
 *         registered resource kit with the given capabilities in relation to the resource.
 * @see #determineContentType(URFResource)
 */
public RK getResourceKit(final Repository repository, final URFResource resource, final Capability... capabilities);

Since the project is public, here is a link for the pull request of what I've done for fixing the javadocs: Bitbucket - Globalmentor's Project: MARMOT-5

Solution

  • Your problem is actually related to the fact that Capability is a static inner class, there are many know issues in the javadoc tool with inner classes, to workaround this problem you should prefix it with its outer class which is ResourceKit in your case.

    So simply replace this

    @see #getResourceKit(Repository, URFResource, Capability...)

    with this

    @see #getResourceKit(Repository, URFResource, ResourceKit.Capability...)

    and this

    {@link #getResourceKit(Repository, URFResource, Capability...)}

    with this

    {@link #getResourceKit(Repository, URFResource, ResourceKit.Capability...)}