Very good point. I struggle with the lack of examples in the API all the time.
What I usually do is go to java.sun.com and do a search on the method (often un-marking the java.sun.com search and sticking only to the
Java Developer stuff). Then scrounge around for an example.
That way I found this explaination (do a find on getInsets in here);
http://developer.java.sun.com/developer/onlineTraining/GUI/AWTLayoutMgr/shortcourse.html and 6 or 7 examples of how to use it