Question about javadoc

[Björn Wessman]

Hello!

If I have methods defined in an interface, should I write functionality detailed information in the java doc in the interface? For example, in my implementation method for find(), I filter out all records I got from my data search that didn't EXACTLY match the criteria. I explain that in the javadoc for the implementer class, but should I do it in the interface as well? It would be useful to have that info right from the top of the hierarchy, but at the same time, that functionality isn't defined until it's actually implemented, and the implementation could change...

How would you guys do?

[Roel De Nijs]

Hi Bjorn,

If I get your interface to reimplement it I have to know what the contract of the method is. So if that method should only return records exactly matching some criteria you have to put it in the javadoc interface. Because that method will be invoked from the GUI and user will see only the matching records. But if you didn't mention it, I would not know of this behavior, so I don't filter records in the reimplementation and user will see a lot more records in the GUI (not exactly matching his search criteria).

From my find-method:

    
    /**
     * Returns an array of record numbers that match the specified criteria.
     * 
     * Field n is described by criteria[n]. A null value in
     * criteria[n] matches any field value, A non-null value in
     * criteria[n] matches any field value that begins with criteria[n]. The
     * matching of field value with the corresponding criterium is
     * case-insensitive, so for example "Fred" matches "Fred", "Freddy", "fred"
     * and "freddy".
     * 
     * If criteria is an array containing only null values, all valid record numbers will be returned.
     * ...
     * @throws IllegalArgumentException if criteria is null
     * ...
     */
    int[] find(String[] criteria) throws RecordNotFoundException;

Kind regards,
Roel

[Björn Wessman]

OK, thanks for the advice. A follow-up question: would you use @inheritDoc or copy-paste the javadoc if they are exactly the same in the interface as in the implementer class?

[Roel De Nijs]

Hi Bjorn,

I used the @inheritDoc, because it's easy and you are certain that both comments are exactly the same. If you copy/paste and afterwards do a small change, you might forget changing it in the class too

Regards,
Roel

[Björn Wessman]

Nevermind, I was looking at the wrong file. The provided interface doesn't have javadoc.