The recommendation is probably about programming to an interface rather than the implementation.

Sure, if you have access to the code then there’s nothing stopping you from looking at the implementation to understand how it works. But you should always make sure that the how doesn’t influence your consumption of the API.

When you’re consuming an API you’re working against an abstraction. Try to concern yourself only with what the API offers (the contract) and not the how (the implementation).

This is because there is no guarantee that an API’s implementation won’t change drastically from one version to the next, even if the contract has remained unchanged.

Aside from the difference between the interface and the implementation, already explained in the previous answer, there is another important aspect: complexity.

Real-life systems are usually complex. If you start reading through the code of a class, you’ll find that you should also go and read the code of another class, then another one, etc. A few hours later, you’ll be simply lost in all the complexity and won’t remember who calls what and in what cases.

When you use only the comments of the interface, you mitigate all this complexity. It might be that under the hood, everything is simple. Or it might be that under the hood, dozens or hundreds of classes interact each other, making it practically impossible to keep the whole image in your head.

You can do an experiment.

• Find a part in OpenCV which interests you. Read through the interface documentation. How long does it take to be able to grasp the basics and effectively use the library?

• Now look at the implementation. How many classes are called directly by the interface? How many classes are called by each of those classes? How many lines of code are there? How many methods? How long it would take you to explore all this source code before having a stack overflow in your brain?

Is there a reason why, or a case when reading only the javadoc is the best thing to do?

While you’re entirely correct that the JavaDoc may be out of date or bad, it does tend to be in a better format for reading wholesale than code in an IDE. And more importantly, it’s in natural language. That is important for two cases:

1. People not used to reading code. University students for example, are likely more often be better served by reading natural language descriptions of functions than trying to understand code that they’re in the process of learning.
2. People who do not use English (or languages that use phonetic alphabets at least) as their primary language. Since JavaDoc can work with characters that identifiers can’t, it can provide better descriptions of what is going on to those users. JavaDoc in particular seems to even have some ability to localize the documentation for you.

That said, I’m a fairly strong believer in readable code. For experienced developers, I expect reading the code to be a better approach almost all of the time if that option is available.