How to write API documentation for constructors in Java

Question

Do I have to write param and return tags for constructors in Java for API documentation?

This is the code I have:

/**
* Another constructor for class Time1
*/
public Time1 (Time1 other) 
    {
        _hour = other._hour; _minute = other._minute; _second = other._second;
    }   

Answer 1

The whole purpose of creating a Documentation is for its implementors to be able to understand what you intended to do in your code.

• Should you create documentationfor everything ? yes The programmers who plan to use your API might not understand the "obvious" purpose of a method,property,constructor,class so, yes, do it even if it is obvious (It might be obvious just to you).

Using @param, @return annotations should be used only when this is the case, in your question code example you have:

/**
* Another constructor for class Time1
*/ public Time1 (Time1 other) 
    {
        _hour = other._hour; _minute = other._minute; _second = other._second;
    }

So, does your constructor return something ? no, so why use the @return annotation. But what your constructor does have is a parameter, so the correct thing to do here would be:

/**
* Another constructor for class Time1
* @param other  <and explain its purpose>
*/
public Time1 (Time1 other) 
    {
        _hour = other._hour; _minute = other._minute; _second = other._second;
    } 

Answer 2

It doesn't make sense to include a return tag for a constructor but other than that, the constructor Javadoc is like any method's Javadoc. You don't have to include a particular tag but you might choose to for various reasons - possibly to elucidate a point about the particular parameter, to highlight under what conditions a particular exception might be thrown, or even just to comply with some in-house coding guidelines.

It's generally a good idea only to include useful information in Javadoc. Something like Another constructor for class Time1 isn't particularly helpful - it doesn't describe why that constructor might be used over another constructor or why this constructor exists.