Those are references, not tutorial. They are there to refresh your memory. Usually you look for code examples or a guide for learning how those work (even AOSP apps if needed)
Those are references, not tutorial. They are there to refresh your memory. Usually you look for code examples or a guide for learning how those work (even AOSP apps if needed)
As far as I recall, many libraries in the Java ecosystem, as well as the Android API, don't have the official tutorials or guides you're referring to. The JavaDoc and the Android API reference are often the only officially available resources.
So no, Those aren't just there to refresh developer's memory. In many cases, they are the only resource for learning the system from scratch.
About JDK Java docs:
This is a great phrase. I fully agree with your sentiment. To me, I never read Javadocs in HTML-only form. I always read them in an IDE, along with the library code in question. If anything is unclear from the Javadoc, then read the code (which immediately follows the Javadoc).I also occasionally fall back to the source when the documentation isn't comprehensive enough.
But as library users, we're generally not supposed to have to learn the system from its source, aren't we?
> Usually you look for code examples or a guide for learning how those work
... which in practice means, particularly for stuff that recently changed, that you go to StackOverflow only to find out that the majority of posts are horribly outdated and don't even compile any more.
The other side are code examples that technically work and show, say, the syntax on how to use a programming language's or framework's shiny new feature... but manage to dumb the code example down so far that one has a very hard time wrapping around one's head on how to use this feature in a real world application.
I was reading The Art of Unix Programming (E. Raymond) and one of the advices was that every library should come with a program. So even it’s a todo list kind, I think it’s quite nice to have.