As you read and understand the code as you go, javadoc it, to make it easier for the next person. You can use UML class diagrams to show the class abstractions you describe. UML sequence diagrams are also very useful to show various runtime scenarios. There are tools which can automatically reverse engineer code into models such as TogetherJ and Ration Rose XDE.
Yes, round-trip engineering tools can help by making diagrams, although for any non-trivial codebase the truth is that these often look like mush, too.
Having a good IDE is invaluable in understanding code. Don't try to read the code in Notepad, or in printouts. Use an IDE with good navigation features so that you can click on a method or class name and instantly go to its definition and find all of its usages. Use an IDE with advanced-enough syntax highlighting that it can display arguments and local, member, and static variables all as different colors (Eclipse 3, IntelliJ IDEA), because this will save you lots of time.
If there are tests, look at the tests! If you're lucky enough to be learning a codebase that was developed using a TDD methodology, then the unit tests should provide excellent examples of how each class is intended to be used: they're better than any manual could be.
Thanks very much for your time and valuable inputs,
I have been using Eclipse and it is of great help indeed. Some methods are documented, but most of the time I come across DOCUMENTME tag. I think it's a good idea to document when I know what a method is doing, not spending too much time ofcouse.
I haven't tried the round trip tools yet, i will certainly look into this option. Speaking to the developers is a good idea, I'll certainly do this more to gain enough knowledge on the APIs.
There are not many test cases written, but I think it's certainly better with the IDE.
your inputs are very much appreciated. Thanks, CNU