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;
    }   

Essayistic

You don't "have to" do that any more than for any other public method, meaning that yeah, you should, otherwise your API documentation is incomplete. – Andry

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;
    } 

Lark

I was thinking that maybe I would need a @return tag due to the constructor does return a new object. – Essayistic

The description of your constructor specifies this, but since the constructor doesn't use the reserved word return then @return is not to be used. – Lark

Should you create documentationfor everything ? yes Not always... You shouldn't provide docs for getters/setters unless they are really useful. – Refurbish

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.

Argo