Sort of.
On the other end of the dependency inversion chain, there is some code that implements those interfaces. That code comes with various caveats that need to be documented.
Then there's the glue code, the orchestration - the part that picks a concrete thing, makes it conform to a desired interface, and passes it to the component which needs it. In order to do its job correctly, this orchestrating code needs to know all the various caveats of the concrete implementation, and all the idiosyncratic demands of the desired interface. When writing this part you may suddenly discover that your glue code is buggy, because the "trivial" interface was thoroughly undocumented.
Please enjoy this silly, but illustrative example!
public interface HerdingCatsService {
/*public static*/ final class Result {
...
}
Result herdThemCats(ABunchOfCats soMuchFun)
throws Exception;
}
Yes, exactly! You want lots of interfaces. You want very small interfaces.
> which in turn increases the need to document those interfaces.
Not if the interfaces are small. For example, in the Go language standard library we find two interfaces: io.Reader and io.Writer. They each define a single method. In the case of io.Reader, that method is defined as Read(p []byte) (n int, err error) and correspondingly io.Writer has Write(p []byte) (n int, err error)
These interfaces are so small they barely need documentation.