Javadoc: Difference between revisions

From NovaOrdis Knowledge Base
Jump to navigation Jump to search
 
(7 intermediate revisions by the same user not shown)
Line 1: Line 1:
=External=
=Internal=
=Internal=


* [[Java#Subjects|java]]
* [[Java#Subjects|java]]
* [[Maven javadoc Plugin|Maven javadoc Plugin]]


=Link to External Content=
=Link to External Content=
Line 14: Line 16:


When implementing an interface method in an implementation class without providing any javadoc for the overridden method, the overridden method automatically inherits the javadoc of the interface method, with some additional clarifying message to the effect that the documentation was inherited:
When implementing an interface method in an implementation class without providing any javadoc for the overridden method, the overridden method automatically inherits the javadoc of the interface method, with some additional clarifying message to the effect that the documentation was inherited:
<syntaxhighlight lang='java'>
public interface A {
    /**
    * This is the interface javadoc.
    */
    public void something();
}
</syntaxhighlight>
<syntaxhighlight lang='java'>
public class AImpl implements A {
    @Override
    public void something() {
        System.out.println("something");
    }
}
</syntaxhighlight>
The resulted AImpl javadoc;


[[File:javadocInterfaces1.png]]
[[File:javadocInterfaces1.png]]


If the overridden method provides its own javadoc, it will overwrite the interface javadoc:
If the overridden method provides its own javadoc, it will overwrite the interface javadoc:
<syntaxhighlight lang='java'>
public class AImpl implements A {
    /**
    * This is documentation for implementation-specific behavior.
    */
    @Override
    public void something() {
        System.out.println("something");
    }
}
</syntaxhighlight>
The resulted AImpl javadoc - note that the interface javadoc was completely overwritten, and this, in most cases, is probably not a good idea::


[[File:javadocInterfaces2.png]]
[[File:javadocInterfaces2.png]]


However, if the overridden
It is possible to provide implementation specific documentation and inherit the interface's javadoc using the {@inheritDoc} tag:
 
<syntaxhighlight lang='java'>
public class AImpl implements A {
 
    /**
    * {@inheritDoc}
    *
    * <br>
    * <br>
    *
    * This is the overridden method javadoc, which documents implementation-specific aspects.
    */
    @Override
    public void something() {


An overridden method automatically inherits the javadoc of its
        System.out.println("something");
    }
}
</syntaxhighlight>


The resulted AImpl javadoc:


If you define javadocs in the subclass they will replace the inherited javadocs, but you can use {@inheritDoc} to include the respective superclass javadoc comments in the subclass javadocs.
[[File:javadocInterface3.png]]

Latest revision as of 17:15, 11 October 2018

External

Internal

Link to External Content

/**
 * For more details see {@linktourl https://example.com}
 */

Inheriting an Overridden Method Comments

When implementing an interface method in an implementation class without providing any javadoc for the overridden method, the overridden method automatically inherits the javadoc of the interface method, with some additional clarifying message to the effect that the documentation was inherited:

public interface A {
    /**
     * This is the interface javadoc.
     */
    public void something();
}
public class AImpl implements A {
    @Override
    public void something() {

        System.out.println("something");
    }
}

The resulted AImpl javadoc;

JavadocInterfaces1.png

If the overridden method provides its own javadoc, it will overwrite the interface javadoc:

public class AImpl implements A {
    /**
     * This is documentation for implementation-specific behavior.
     */
    @Override
    public void something() {

        System.out.println("something");
    }
}

The resulted AImpl javadoc - note that the interface javadoc was completely overwritten, and this, in most cases, is probably not a good idea::

JavadocInterfaces2.png

It is possible to provide implementation specific documentation and inherit the interface's javadoc using the {@inheritDoc} tag:

public class AImpl implements A {

    /**
     * {@inheritDoc}
     *
     * <br>
     * <br>
     *
     * This is the overridden method javadoc, which documents implementation-specific aspects.
     */
    @Override
    public void something() {

        System.out.println("something");
    }
}

The resulted AImpl javadoc:

JavadocInterface3.png