Reuse Code Documentation with @inheritDoc

Documentation is a crucial aspect of coding, providing insights into the purpose and functionality of various methods and properties. However, maintaining clear and concise documentation can sometimes be a repetitive task, especially when dealing with inherited methods or interfaces. This is where the @inheritDoc tag comes into play, offering a convenient solution for inheriting documentation from parent classes or interfaces, thus eliminating the need for redundant documentation.

 

The @inheritDoc tag serves as a powerful tool for writing efficient documentation practices. By simply including this tag within the documentation comments block of a method or property, developers can seamlessly inherit documentation from higher up in the inheritance hierarchy. Let's delve into how this tag works and explore its benefits through practical examples.

 

Consider the following scenario: you have a method sum(int a, int b) within a class implementing an interface, and you wish to inherit the documentation from the interface for this method. Instead of duplicating the documentation, you can utilize the @inheritDoc tag. Here's how it's done:

/**
 * Bare minimal implementation.<br />
 * 
 * {@inheritDoc}
 * 
 * 
 */
@Override
public int sum(int a, int b) {
    return a + b;
}

 

In this example, the documentation for the sum method is inherited from the nearest inheritable class or implementable interface, allowing for concise and consistent documentation throughout the codebase.

 

The @inheritDoc tag isn't limited to method descriptions; it can also be used within the @return, @param, and @throws tags of a method, ensuring comprehensive documentation inheritance.

 

It's important to note that while inherited documentation provides a solid foundation, implementing classes or methods can still include their own documentation comments, either fully or partially overriding the inherited documentation. This flexibility allows developers to tailor documentation to specific implementations while leveraging the clarity and coherence of inherited documentation.

 

Find the below working application.

 

ArithmeticService.java

package com.sample.app.util;

/**
 * The ArithmeticService interface defines methods for performing arithmetic
 * operations. Implementations of this interface should provide functionality
 * for addition and subtraction.
 */
public interface ArithmeticService {

	/**
	 * Returns the sum of two integers.
	 *
	 * @param a the first integer operand
	 * @param b the second integer operand
	 * @return the sum of the two integers
	 */
	public int sum(int a, int b);

	/**
	 * Returns the result of subtracting the second integer from the first integer.
	 *
	 * @param a the minuend (the number to be subtracted from)
	 * @param b the subtrahend (the number to subtract)
	 * @return the result of subtracting the second integer from the first integer
	 */
	public int sub(int a, int b);

}

 

BasicArithmeticServiceImpl.java

package com.sample.app.util;

public class BasicArithmeticServiceImpl implements ArithmeticService {

	/**
	 * Bare minimal implementation.<br />
	 * 
	 * {@inheritDoc}
	 * 
	 * 
	 */
	@Override
	public int sum(int a, int b) {
		return a + b;
	}

	/**
	 * Bare minimal implementation.<br />
	 * 
	 * {@inheritDoc}
	 */
	@Override
	public int sub(int a, int b) {
		return a - b;
	}

}

Above snippet generate below documentation for BasicArithmeticServiceImpl class.

 

 

 

Previous                                                 Next                                                 Home