What is the proper "@link" or "@see" javadoc tag for inner/nested class constructors?

Question

I have had problems getting "@link" and "@see" tags to work for constructors of inner/nested classes and hope someone here can help. This short example class gives javadoc warnings on Line 25 referencing the "@link" and (equivalent) "@see" tags on the preceding lines of the "Layer()" documentation.

package bogus;
import javax.swing.JPanel;
public class LayeredPlot extends JPanel {
  /**
   * Constructor for the plot.
   */
  public LayeredPlot() {
  }
  public static class Layer {
    private String name;
    /**
     * Construct a default layer with a default name. This method calls
     * {@link LayeredPlot.Layer#Layer(String)} OR calls == JAVADOC WARNING
     * {@link #Layer(String)} OR calls                  == JAVADOC WARNING
     * {@link Layer#Layer(String)}                      == JAVADOC WARNING
     * with a null name to perform the construction.
     * The constructor for the layer can be found
     * {@link LayeredPlot#LayeredPlot() here}.          == JAVADOC Okay!
     *
     * @see LayeredPlot.Layer#Layer(String)             == JAVADOC WARNING
     * @see #Layer(String)                              == JAVADOC WARNING
     * @see Layer#Layer(String)                         == JAVADOC WARNING
     * @see LayeredPlot#LayeredPlot()                   == JAVADOC Okay!
     */
    public Layer() {    // Line 25: javadoc warnings reference this line
      this(null);
    }
    /**
     * Construct a layer with the specified name.
     *
     * @param name The desired name for the layer within the plot.
     */
    public Layer(String name) {
      this.name = name;
    }
  }
}

The warnings (3 for "@see", 3 for "@link") all say: can't find Layer(String) in bogus.LayeredPlot.Layer.

PLEASE NOTE: All other javadocs work as expected (including inner class methods and my references in this example to the constructor of LayeredPlot itself).

Any suggestions for correct javadoc tags for inner/nested class constructors would be greatly appreciated.
Thanks.

Answer 1

There is no proper way to do that with Java 8 or earlier, because of bug JDK-8031625, which is fixed only in Java 9.

The workaround is to use fully qualified names, for class and parameters:

{@link bogus.LayeredPlot.Layer#LayeredPlot.Layer(java.lang.String)}

But this is not a syntactically valid member name, so several tools will complain (doclint, checkstyle).

Answer 2

If you scope the inner name at all, you need to fully scope it on both sides of the # marker. E.g.:

@see LayeredPlot.Layer#LayeredPlot.Layer(String)