{"id":62052,"date":"2016-11-22T19:00:05","date_gmt":"2016-11-22T17:00:05","guid":{"rendered":"https:\/\/www.javacodegeeks.com\/?p=62052"},"modified":"2016-11-22T12:06:09","modified_gmt":"2016-11-22T10:06:09","slug":"inheriting-javadoc-method-comments","status":"publish","type":"post","link":"https:\/\/www.javacodegeeks.com\/2016\/11\/inheriting-javadoc-method-comments.html","title":{"rendered":"Inheriting Javadoc Method Comments"},"content":{"rendered":"

Although the JDK Tools and Utilities<\/a> pages for the javadoc tool<\/a> describe the rules of Javadoc method comment reuse by implementing and inheriting methods, it is easy to unnecessarily explicitly describe comment inheritance with {@inheritDoc}<\/code> when it’s not really needed because the same comments would be implicitly inherited. The Java 8 javadoc tool page<\/a> describes the rules of inherited method Javadoc comments under the section “Method Common Inheritance<\/a>” and the Java 7 javadoc tool page<\/a> similarly describes these rules under the section “Automatic Copying of Method Comments<\/a>.” This post uses simple code examples to illustrate some of the key rules of Javadoc method comment inheritance.<\/p>\n

The following interfaces and classes are contrived examples that will be used in this post to illustrate inheritance of Javadoc comments on methods. Some inherited\/implementing methods include their own Javadoc comments that override parent’s\/interface’s methods comments fully or partially and other simply reuse the parent’s\/interface’s methods’ documentation.<\/p>\n

Herbivorous Interface<\/strong><\/p>\n

package dustin.examples.inheritance;\r\n\r\n\/**\r\n * Marks animals that eat plants.\r\n *\/\r\npublic interface Herbivorous\r\n{\r\n   \/**\r\n    * Eat the provided plant.\r\n    *\r\n    * @param plantToBeEaten Plant that will be eaten.\r\n    *\/\r\n   void eat(Plant plantToBeEaten);\r\n}<\/pre>\n
Carnivorous Interface<\/strong><\/p>\n
package dustin.examples.inheritance;\r\n\r\n\/**\r\n * Marks an Animal that eats other animals.\r\n *\/\r\npublic interface Carnivorous\r\n{\r\n   \/**\r\n    * Eat the provided animal.\r\n    *\r\n    * @param animalBeingEaten Animal that will be eaten.\r\n    *\/\r\n   void eat(Animal animalBeingEaten);\r\n}<\/pre>\n
Omnivorous Interface<\/strong><\/p>\n
package dustin.examples.inheritance;\r\n\r\n\/**\r\n * Eats plants and animals.\r\n *\/\r\npublic interface Omnivorous extends Carnivorous, Herbivorous\r\n{\r\n}<\/pre>\n
Viviparous Interface<\/strong><\/p>\n
package dustin.examples.inheritance;\r\n\r\n\/**\r\n * Mammals that give birth to young that develop within\r\n * the mother's body.\r\n *\/\r\npublic interface Viviparous\r\n{\r\n   \/**\r\n    * Give birth to indicated number of offspring.\r\n    *\r\n    * @param numberOfOffspring Number of offspring being born.\r\n    *\/\r\n   void giveBirth(int numberOfOffspring);\r\n}<\/pre>\n
Animal Class<\/strong><\/p>\n
package dustin.examples.inheritance;\r\n\r\n\/**\r\n * Animal.\r\n *\/\r\npublic abstract class Animal\r\n{\r\n   \/**\r\n    * Breathe.\r\n    *\/\r\n   public void breathe()\r\n   {\r\n   }\r\n\r\n   \/**\r\n    * Communicate verbally.\r\n    *\/\r\n   public abstract void verballyCommunicate();\r\n}<\/pre>\n
Mammal Class<\/strong><\/p>\n
package dustin.examples.inheritance;\r\n\r\n\/**\r\n * Mammal.\r\n *\/\r\npublic abstract class Mammal extends Animal\r\n{\r\n}<\/pre>\n
MammalWithHair Class<\/strong><\/p>\n
package dustin.examples.inheritance;\r\n\r\nimport java.awt.*;\r\n\r\n\/**\r\n * Mammal with hair (most mammals other than dolphins and whales).\r\n *\/\r\npublic abstract class MammalWithHair extends Mammal\r\n{\r\n   \/** Provide mammal's hair color. *\/\r\n   public abstract Color getHairColor();\r\n}<\/pre>\n
Dog Class<\/strong><\/p>\n
package dustin.examples.inheritance;\r\n\r\nimport java.awt.Color;\r\n\r\nimport static java.lang.System.out;\r\n\r\n\/**\r\n * Canine and man's best friend.\r\n *\/\r\npublic class Dog extends MammalWithHair implements Omnivorous, Viviparous\r\n{\r\n   private final Color hairColor = null;\r\n\r\n   \/**\r\n    * {@inheritDoc}\r\n    * @param otherAnimal Tasty treat.\r\n    *\/\r\n   @Override\r\n   public void eat(final Animal otherAnimal)\r\n   {\r\n   }\r\n\r\n   \/**\r\n    * {@inheritDoc}\r\n    * @param plantToBeEaten Plant that this dog will eat.\r\n    *\/\r\n   @Override\r\n   public void eat(final Plant plantToBeEaten)\r\n   {\r\n   }\r\n\r\n   \/**\r\n    * {@inheritDoc}\r\n    * Bark.\r\n    *\/\r\n   public void verballyCommunicate()\r\n   {\r\n      out.println(\"Woof!\");\r\n   }\r\n\r\n   \/**\r\n    * {@inheritDoc}\r\n    * @param numberPuppies Number of puppies being born.\r\n    *\/\r\n   @Override\r\n   public void giveBirth(final int numberPuppies)\r\n   {\r\n   }\r\n\r\n   \/**\r\n    * Provide the color of the dog's hair.\r\n    *\r\n    * @return Color of the dog's fur.\r\n    *\/\r\n   @Override\r\n   public Color getHairColor()\r\n   {\r\n      return hairColor;\r\n   }\r\n}<\/pre>\n
Cat Class<\/strong><\/p>\n
package dustin.examples.inheritance;\r\n\r\nimport java.awt.Color;\r\n\r\nimport static java.lang.System.out;\r\n\r\n\/**\r\n * Feline.\r\n *\/\r\npublic class Cat extends MammalWithHair implements Carnivorous, Viviparous\r\n{\r\n   private final Color hairColor = null;\r\n\r\n   \/**\r\n    * {@inheritDoc}\r\n    *\/\r\n   @Override\r\n   public void eat(final Animal otherAnimal)\r\n   {\r\n   }\r\n\r\n   @Override\r\n   public void verballyCommunicate()\r\n   {\r\n      out.println(\"Meow\");\r\n   }\r\n\r\n   @Override\r\n   public void giveBirth(int numberKittens)\r\n   {\r\n   }\r\n\r\n   @Override\r\n   public Color getHairColor()\r\n   {\r\n      return hairColor;\r\n   }\r\n}<\/pre>\n
Horse Class<\/strong><\/p>\n
package dustin.examples.inheritance;\r\n\r\nimport java.awt.Color;\r\n\r\nimport static java.lang.System.out;\r\n\r\n\/**\r\n * Equine.\r\n *\/\r\npublic class Horse extends MammalWithHair implements Herbivorous, Viviparous\r\n{\r\n   private final Color hairColor = null;\r\n\r\n   \/**\r\n    * @param plant Plant to be eaten by this horse.\r\n    *\/\r\n   @Override\r\n   public void eat(final Plant plant)\r\n   {\r\n   }\r\n\r\n   \/**\r\n    *\r\n    *\/\r\n   @Override\r\n   public void verballyCommunicate()\r\n   {\r\n      out.println(\"Neigh\");\r\n   }\r\n\r\n   \/**\r\n    * @param numberColts Number of colts to be born to horse.\r\n    *\/\r\n   @Override\r\n   public void giveBirth(int numberColts)\r\n   {\r\n   }\r\n\r\n   @Override\r\n   public Color getHairColor()\r\n   {\r\n      return hairColor;\r\n   }\r\n}<\/pre>\n
The next screen snapshot shows the contents of the package that includes the interfaces and classes whose code listings are shown above (not all the classes and interfaces in the package had their code listings shown).
 
<\/div> <\/div><\/p>\n
\"20161116-inheritancepackagejavadoc\"<\/a><\/p>\n
The three classes of most interest here from methods’ Javadoc perspective are the classes Dog<\/code>, Cat<\/code>, and Horse<\/code> because they implement several interfaces and extend MamalWithHair<\/code>, which extends Mammal<\/code>, which extends Animal<\/code>.<\/p>\n
The next screen snapshot is of the Javadoc for the Animal<\/code> class rendered in a web browser.<\/p>\n
\"20161119-animaljavadoc-1\"<\/a><\/p>\n
The Animal<\/code> class doesn’t inherit any methods from a superclass and doesn’t implement any methods from an interface and is not very interesting for this blog post’s topic. However, other classes shown here extend this class and so it is interesting to see how its method comments affect the inheriting classes’ methods’ descriptions.<\/p>\n
The next two screen snapshots are of the Javadoc for the Mammal<\/code> and MammalWithHair<\/code> classes as rendered in a web browser. There are no Javadoc comments on any significance on Mammal<\/code>, but there is one method comment for a new method introduced by MammalWithHair<\/code>.<\/p>\n
\"20161119-mammaljavadoc\"<\/a><\/p>\n
\"20161119-mammalwithhairmethodsummary\"<\/a><\/p>\n
The next three screen snapshots are of subsets of Javadoc documentation in a web browser for the interfaces Herbivorous<\/code>, Carnivorous<\/code>, and Omnivorous<\/code>. These interfaces provide documentation for methods that will be inherited by classes that implement these methods.<\/p>\n
\"20161119-herbivorousjavadoc\"<\/a><\/p>\n
\"20161119-carnivorousjavadoc\"<\/a><\/p>\n
\"20161119-omnivorousjavadoc\"<\/a><\/p>\n
With the generated Javadoc methods documentation for the parent classes and the interfaces shown, it’s now time to look at the generated documentation for the methods of the classes extending those classes and implementing those interfaces.<\/p>\n
The methods in the Dog<\/code> class shown earlier generally used {@inheritDoc}<\/code> in conjunction with additional text. The results of inheriting method Javadoc comments from extended classes and implemented interfaces combined with additional test provided in Dog<\/code>‘s comments are shown in the next screen snapshots.<\/p>\n
\"20161119-dogjavadocmethodsummary\"<\/a><\/p>\n
\"20161119-dogjavadocmethoddetailtop\"<\/a><\/p>\n
\"20161119-dogjavadocmethoddetailbottom\"<\/a><\/p>\n
The last set of screen snapshots demonstrates that the Dog<\/code> class’s documentation mixes the documentation of its “parents” with its own specific documentation. This is not surprising. The Dog<\/code> class’s methods generally explicitly inherited Javadoc documentation from the parents (base classes and interfaces), but the Cat<\/code> class mostly has no Javadoc comments on its methods, except for the eat<\/code> method, which simply uses {@inheritDoc}<\/code>. The generated web browser output from this class is shown in the next screen snapshots.<\/p>\n
\"20161119-catjavadocmethodsummary\"<\/a><\/p>\n
\"20161119-catjavadocmethoddetail\"<\/a><\/p>\n
The methods in Cat<\/code> that had no Javadoc comments applied show up in the generated web browser documentation with documentation inherited from their base classes or interfaces and the documentation on these methods includes the phrase “Description copied from class:” or “Description copied from interface:” as appropriate. The one Cat<\/code> method that does explicitly include the documentation tag {@inheritDoc}<\/code> does copy the parent’s method’s documentation, but does not include the “Description copied from” message.<\/p>\n
The Horse<\/code> class’s methods are generally not documented at all and so their generated documentation includes the message “Description copied from…”. The eat()<\/code> and giveBirth()<\/code> methods of the Horse<\/code> class override the @param<\/code> portion and so the parameter documentation for these two methods in the generated web browser documentation (shown in the next set of screen snapshots) is specific to Horse<\/code>.<\/p>\n
\"20161119-horsemethodsummary\"<\/a><\/p>\n
\"20161119-horsemethoddetailtop\"<\/a><\/p>\n
\"20161119-horsemethoddetailbottom\"<\/a><\/p>\n
From the above code listings and screen snapshots of generated documentation from that code, some observations can be made regarding the inheritance of methods’ Javadoc comments by extending and implementing classes. These observations are also described in the javadoc tool documentation<\/a>:<\/p>\n