Documenting logic in javadoc
- by smayers81
I have a question about where to document logic in javadocs. For example, I have the following method signature in an interface:
public int getTotalAssociationsAsParent(Long id, Long type);
The method returns associations where the given ID is the parent and the association is of type 'type'. ID is required, but if type passed in is NULL, then I will return ALL associations where the ID is the parent.
My question is where should this type of logic be documented? I hesitate putting it in the javadoc of the interface because that sort of constrains all implementing classes to adhere to that logic. Maybe in the future, I'll have an Impl class that throws an IllegalArgumentException if type is NULL.
However, if I put it in non-javadoc in the Impl class, then consumers of this method won't know how the method behaves with a NULL type.
