How to efficiently write documentation for API?

Question

I almost finished work on my API.

And now I need to write javadocs for all interfaces and their methods and my brains go into melt because I don't know what to write there. I have some thoughts on how to write docs for methods but I have no idea what to write for interfaces.

Any general suggestions?

Answer 1

Maybe you could take a look on how are interfaces documented.

For example

http://java.sun.com/j2se/1.4.2/docs/api/java/util/List.html

contains

public boolean contains(Object o)

    Returns true if this list contains the specified element. More formally, returns true if and only if this list contains at least one element e such that (o==null ? e==null : o.equals(e)).

    Specified by:
        contains in interface Collection

    Parameters:
        o - element whose presence in this list is to be tested. 
    Returns:
        true if this list contains the specified element. 
    Throws:
        ClassCastException - if the type of the specified element is incompatible with this list (optional). 
        NullPointerException - if the specified element is null and this list does not support null elements (optional).

As you can see, it contains no implemnetation detail, just a general description, including exceptions, return values, etc.

Anyone who reads your interface documentation should know exactly whats the price to pay for implementing it.