How should I structure my TCL code? - tcl

Im new to TCl-facing some problems learning it.
However I need to know if any one of you have some script or any idea so that I could make my code more structured ie more readable

Personally I would recommend this and this articles by Will Duquette, if we're talking about "plain" Tcl (that is, not armed with any extensions aimed at better structuring).
You can do object orientation with Tcl, too. Tcl 8.6 will be equipped with a core OO package, but there is a whole lot of readily available OO frameworks. Personally, I've successfully used Snit as a plain Tcl OO system.

This "TCL for Web Nerds" book by Philip Greenspun is very easy to read, and while it's a bit dated, is a great introduction to TCL (especially if you're doing any web programming). I still refer to it occasionally along with the TCL manuals and the Wiki (although to be honest I often the wiki too obscure for many of my needs).

Except for #kostix excellent "advanced" answer, take these basic Tcl beginner tips into account:
avoid the global top level for writing your code, pack in into Proc-edures
avoid global variables and use namespaces (see answer #kostix)
learn about upvar to pass variables by reference
read other tcl code examples by other experienced tcl users

Related

Extending embedded Python in C++ - Design to interact with C++ instances

There are several packages out there that help in automating the task of writing bindings between C\C++ and other languages.
In my case, I'd like to bind Python, some options for such packages are: SWIG, Boost.Python and Robin.
It seems that the straight forward process is to use these packages to create C\C++ linkable libraries (with mostly static functions) and have the higher language be extended using them.
However, my situation is that I already have a developed working system in C++ therefore plan to embed Python into it so that future development will be in Python.
It's not clear to me how, and if at all possible, to use these packages in helping to extend embedded Python in such a way that the Python code would be able to interact with the various Singleton instances already running in the system, and instantiate C++ classes and interact with them.
What I'm looking for is an insight regarding the design best fitted for this situation.
Boost.python lets you do a lot of those things right out of the box, especially if you use smart pointers. You can even inherit from C++ classes in Python, then pass instances of those back to your C++ code and have everything still work. My favorite resource on how to do various stuff is this (especially check out the "How To" section): http://wiki.python.org/moin/boost.python/ .
Boost.python is especially good if you're using smart pointers or intrusive pointers, as those translate transparently into PyObject reference counting. Also, it's very good at making factory functions look like Python constructors, which makes for very clean Python APIs.
If you're not using smart pointers, it's still possible to do all the things you want, but you have to mess with various return and lifetime policies, which can give you a headache.
To make it short: There is the modern alternative pybind11.
Long version: I also had to embed python. The C++ Python interface is small so I decided to use the C Api. That turned out to be a nightmare. Exposing classes lets you write tons of complicated boilerplate code. Boost::Python greatly avoids this by using readable interface definitions. However I found that boost lacks a sophisticated documentation and dor some things you still have to call the Python api. Further their build system seems to give people troubles. I cant tell since i use packages provided by the system. Finally I tried the boost python fork pybind11 and have to say that it is really convenient and fixes some shortcomings of boost like the necessity of the use of the Python Api, ability to use lambdas, the lack of an easy comprehensible documentation and automatic exception translation. Further it is header only and does not pull the huge boost dependency on deployment, so I can definitively recommend it.

Complex GUI in clojure

I just started using clojure today (however , I have used Java a lot and know of functional paradigms) and I was wondering if it was a good idea to build a clojure app with a reasonable complex interface (dragging, dropping, panning, zooming,...) using Swing?
I can imagine that a lot of the normal swing logics (especially concerning OO) has to be bypassed one way or the other..
I asume that all is possible , but is it possible in a way that justifyable?
I mean wouldn't it be like hitting a nail with a screwdriver in stead of with a hammer?
Has anyone here have experience in building GUI's with Clojure (and of Course : is Swing the ideal candidate for that?)
Thanks !
I've found it relatively easy to use Swing to build decent user interfaces in Clojure. You have a couple of options about how to do it however:
Write the code pretty much as you would in Java, just using the Java interop from Clojure to call the relevant Swing APIs. This article does a good job of explaining how, with a bit of macro magic as well to make your life easier.
Use a Clojure GUI wrapper for Swing, e.g. seesaw or clj-swing. My take is that these tools have the potential to help you write some really neat GUI code in idiomatic Clojure
One really cool feature of Clojure's software transactional memory subsystem is that it allows you to set watches on variables: whenever the variable is changed (by anything), your callback gets executed. This lends itself to a powerful sort of GUI programming where the GUI updates itself automagically based on the state of your variables.
A short but non-trivial Swing GUI example is described in detail at http://www.paullegato.com/blog/swing-clojure-gui-black-scholes/ .
Since others are mentioning swing related answers, I'll ask you one question: Is Swing a requirement. Although writing Swing code in clojure is more pleasant then in Java, it is still Swing, with all its verbosity and annoyances, especially in complex application with hard set requirements.
Have you considered web UI, where Clojure fits much more natural? Or SWT or QT Jambi, which also can be made to work using Clojure.

What general purpose language should I learn next?

I'm currently participating in a programming contest (http://contest.github.com), which has as goal, to create a recommendation engine. I started coding in ruby, but soon realised it wasn't fast enough for the algorithms I had in mind. So I switched to C, which is the only non-scripting language I know. It was fast, of course, but I cringed every time I had to write a for loop, to go through the elements of an array (which was very often).
That's when it dawned: I wish I knew a fast, yet high-level language, to program all these intensive computations with ease!
So I looked at my options, but there are a lot of options these days! Here the best candidates I've found over the months, with something which bothers me about each of them (that hopefully you can clear up):
Clojure: I'm not sure I want to get into the whole lisp thing, I like my syntax and cruft. I could be convinced, though.
Haskell: Too academic? I don't really care for pure functional, I just want something which works. But it has nice syntax, and I don't mind static typing.
Scala: Weird language. I tried it out but it feels messy/inconsistent to me.
OCaml: Also wondering if this is too academic? The poor concurrency support also bothers me.
Arc: Paul Graham's lisp, too obscure, and again, I'm not sure I want to learn a lisp. But I trust this man!
Any advice? I really like the functional languages, for their ability to manipulate lists with ease, but I'm open to other options too. I'd like something about as fast as Java..
The kind of things I want to be able to do with lists are like (ruby):
([1, 2, 3, 4] - [2, 3]).map {|i| i * 2 } # which results in [2, 8]
I would also prefer an open-source language.
Thanks
Out of the languages that you've listed, neither Haskell nor Arc match your "fast" requirement - both are slower than Java. Your idea that Haskell is faster than Java and approaches C is most likely coming from one well-known flawed test that tried to measure performance by implementing sort. One thing that they've missed is that Haskell is lazy, and thus you need to use the results of the sort for it to actually perform that; and they measured performance simply by remembering current time, "calling" the sort function, and checking the time delta. C version of the test faithfully performed the sort, Haskell version simply returned a thunk for lazy evaluation which was never called.
In practice, there are a number of reasons why Haskell cannot be that fast even in theory. First, because of pervasive lazy evaluation, it often cannot pass around raw values, and has to generate thunks for expressions - the optimizer can trim down on those in trivial cases, but not for more complicated ones. Second, polymorphic Haskell functions are implemented as runtime-polymorphic, and not like C++ templates where every new type parameter instantiates a new version of code that is optimally compiled. Obviously, this necessitates extra boxing/unboxing. In the end, Haskell will struggle to beat any decent VM (such as HotSpot JVM, or CLR in .NET 2.0+), much less C/C++.
Now that's settled in, let's move on to the rest. Scala uses JVM as a backend, and thus is not going to be any faster than Java - and if you use higher-level abstractions, it will most likely be slower somewhat, but probably in the same ballpark. Clojure also runs on JVM, but it's also dynamically typed, and that carries an unavoidable performance penalty (I heard it does clever tricks to mitigate that to some extent, but some of it really is unavoidable no matter what).
That leaves OCaml, and out of your list, it is the only language that had actually been conclusively shown to reach the performance of C/C++ compilers on valid tests. It should be noted however that this would not be typical of idiomatic OCaml code - for example, its polymorphism is also runtime, similar to Haskell, and that carries the appropriate penalty; also, its OOP system is structural rather than nominal, which precludes an optimal vtable-based implementation; so that is going to be slower than C++, too (I'd expect perf penalty close to that of Objective-C dispatch compared to C++ dispatch, but I don't have any numbers to back that up). So you can beat C++ in OCaml if you steer away from certain language features, but unfortunately, it's those features that make OCaml so attractive in the first place.
My advice would be this: if you really need speed, go with C++. It can be fairly high-level if you use high-level libraries such as STL and Boost. It doesn't have some high-level language abstractions you might be used to, but libraries can compensate for that - sometimes fully, sometimes in part. For example, you don't have to write a for-loop to iterate over an array - you can use std::for_each, std::copy_if, std::transform, std::accumulate and similar algorithms (which are mostly analogous to map, filter, fold, and similar traditional FP primitives), and also Boost.Lambda to cut down on boilerplace.
Why not simple Java or C#? Should be faster then Ruby, more high level then C and have a huge userbase.
Your criticism of pretty much everything seems to be that it's "weird" or "too academic." But what does that mean? It's the sort of vague criticism that you can throw at any unfamiliar language that isn't totally mainstream (i.e., not C, C++, Objective-C, Java, Ruby, Python or PHP). There's nothing about all those languages that's inherently good for academia and bad for anything else. Try to break down your analysis a little further: Specifically, what is it that troubles you about those languages? You might find that your brain is just instinctively pushing away something unfamiliar. If that's the case, learning one of those languages might be a good way to expand your mind.
Alternatively: It sounds like you're looking for a functional language, so you might look at F#. It's a first-class CLR language created by Microsoft, so it doesn't carry any "academic" mental baggage, and it's very similar to OCaml.
newLISP is fast, small, integrates extremely easily with C, and it has quite a few statistical functions built-in.
Haskell is my current preference as a performant, high-level language. I've also heard very good things about OCaml, but haven't personally used it much.
Scala and Clojure will have similar performance to Java -- slow, slow, slow! Sure, they'll be faster than Ruby, but what isn't?
Arc is a set of macros for MzScheme, and is not particularly fast. If you want a performant LISP, try Common LISP -- it can be compiled to machine code.
How about Delphi / FreePascal? They're native code & fast. I do a lot of real-time graphics & processing with them. They dont require that you work 'low level', but you can if you need to. Plus you can embed assembler if needed for extra performance. FreePascal is cross platform if you want to stay off Windows.
D might fit the bill? Compiles to machine code but allows for programming using higher-level concepts.
Python can be made to run fast, especially using the NumPy package. Relevant links below:
http://www.scipy.org/PerformancePython
Cython and numpy speed
You seem uncomfortable with any language that doesn't look like one you already use. That's going to limit you, so I'd suggest one you won't be comfortable with if you're interested in expanding your horizons. I'm not saying you'll want to continue with any particular language (I have a definite preference never to touch Tcl again), but you should try it sometime.
There are nice fast implementations of Common Lisp, and that's an easy language to write functional programs in. Besides, if you can get along with it, you'll find a lot of neat things you can do with it.
Computation? Fortran. Beats the pants off of anything else.
If you don't mind .NET...
F# - based on O'Caml, multiparadigm language with full access to .NET Framework. Included officially in .NET FW 4.0
Nemerle - see F# and add to that a POWERFUL metaprogramming capabilities.
After your update:
If you want to manipulate lists easily you should go with Common Lisp. It is only 2 times slower that C in average (and actually faster in some things), it is great for list processing and it is multi-paradigm (imperative, functional and OO) - so you don't have to stick to functional-only programming. SBCL is a good Common Lisp to try first, IMO.
And don't get bothered by strange "lispy" things like parentheses. It is not only quite stupid to judge language by its syntax, rather than semantics, but also parentheses are one of the greatest strengths of LISP, because they eliminate differences between data and expressions and you can manipulate language itself to make it fit your needs.
Don't listen to people who advice C++/C#/Java. Java functional part is non-existant. C++ functional part is terrible. C# delegates makes me sick because of their complexity. They are not REAL multi-paradigm imperative/functional languages, they are imperative/OO languages that have some small functional bits, you can't do real functional programming in them.
C++ or alternatively C# and mono.
Honestly, to accomplish much in the world of software engineering, you will likely have to wrap your head around these languages you find distasteful. Java, C, C++, C#, etc. are likely to come up in a career that involves programming.
Looks like you've done some interesting work. I encourage you to push your technical skills harder. It will be worth the effort.
Alternatively, Python might be good, given your interests. You might find Smalltalk interesting, or even ATS.
For some ideas, look at the Language Shootout and analysis by Oscar Boykin. You have already discovered this, but comparing Ruby to C we see that Ruby is between 14 and 600 times slower (several tests are more than 100 times slower). He also points out that Python is faster than Ruby. The benchmarks for all languages is interesting.
Also interesting are benchmarks from Dan Corlan.
You might consider python; it supports writing modules in C or C++, so you can get it working in a high-level language, profile it, rework the algorithms, and if it still isn't fast enough, translate the hotspots to C or C++ for speed.
Consider Tcl, combined with C. Do the really compute-intensive stuff in C since that's what you know how to do, then use Tcl as the glue to combine the high level code with your C-based code.
I make this recommendation not because Tcl is necessarily the best language for the job (there really is no "best" for something like this) but because you'll learn a lot about the concept of combining the strengths of two different languages. It's an important technique that could serve you well in your career whether it's Tcl/C, Lua/C, Groovy/Java, Python/C, etc.
Python with pyrex or psyco may be a better fit? Probably not as fast as C, but you can see some significant speedups from regular Python.
If you want something that's "about as fast as Java," the obvious solution is JRuby.
If you install Netbeans (use the download button under the Ruby column), JRuby is the default interpreter. It doesn't get much easier!
If your problem is C's clunky loops, I'd suggest looking at Ada. It allows you to loop through a whole array with a simple statement like so:
for I in array_name'range loop
--'// Code goes here
end loop;
For AI projects, I'd also suggest you look into using Clips, which is a freely-available inference engine.
Rather than OCAML, you might consider F# -- it's source compatible with OCAML (or you can use a lighter weight syntax) and it supports actor-style concurrency with what it calls asynchronous workflows (which are really an almost-monad for applying asynchronous execution).
Not that -- as Scala shows -- you need to have actor style concurrency baked into the language, if you build it into a library. The rest is just syntactic sugar.
Learn C++ and familiarize yourself with its standard library. It won't be that hard to learn as you already 'speak' C, but keep in mind that C++ is not just a better C, it's another language with its own concepts and methods.
Why not Erlang?
It's not too much like the languages you already know, so you can learn new concepts
It has some interesting capabilities for multiprocessing
It's not out of academia. Erlang was a commercial language first.
There are at least two significant open source applications written in it: CouchDB and Wings3d
I believe going through C C++ and Java or .net then moving on from here to any one way java or .net , because c is more machine oriented and C++ and java will give you hands on with object oriented learning, then later on switching to python (to really appreciate the clean code than in C C++ and JAVA ).

worth to learn groovy? [closed]

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
Improve this question
the question im asking, is it worth to learn a new language like groovy? cause if i learn groovy, it feels like i code in groovy and not java. and how smart is that when i have to be good in java to code desktop applications too in the future. so if i use groovy a lot for web applications, i will just be worse and have to start over to be good in java when i code desktop applications right?
so why don´t I just stick with java and be good at ONE language instead of having to switch between 2 languages and their syntax. Cause it would be so confusing...
Groovy is a nice, scriptable and easier-to-use Java "knockoff" – and I don't mean that derogatively. while Java is a language to be compiled, deployed and (often) run on Enterprise servers where performance matters, Groovy is a language where you can quickly create a program to get something done. Often that something is fairly simple, so it's an hour's or a day's coding effort. Often the code is only run once and then thrown away. Because Java has more boilerplate and formalism in it, you can do this kind of program more quickly and hence more efficiently in Groovy.
However, just to give you some perspective, Groovy is a relative newcomer stomping on the turf of various other, better established scripting languages:
Perl is one of the grandfathers of scripting languages; rarely does a Unix server get installed without Perl on it, and Perl scripts are the lifeblood of many servers. However, Perl is a write-only language that looks like line noise to the uninitiated. There's more than one way to do everything, so styles diverge drastically. Perl coding tends to be a bit messy.
Python is a fresher, cleaner script language than Perl, and is these days preferred by many as a scripting language. It's fun to program in, it gets things done and because it's been around for a few years, lots of people know it. Python is found behind/inside a number of Linux system utilities.
Groovy leaves Perl and Python in the dust when (a) the environment already makes use of a JVM and/or there's a requirement to use existing Java code, including libraries. So far so good. Groovy is not blazingly fast, but faster than Python. Being dynamically typed, it's "fun" and "easy" to program in a way that Java's not.
But then came Scala. Scala is like Java on steroids. It is statically typed so it's not quite as "fun" to program as Groovy, but it has type inference so often you can leave off the types and the compiler can figure them out. Scala works really hard to make the most of types; it does generic types a lot more seamlessly than Java. It dispenses with a lot of Java's boilerplate, so Scala programs are typically about 30% shorter than similar Java programs. Scala runs on the JVM and interfaces pretty well with Java code. It also runs about as quickly as Java, which most of the other languages don't.
Finally in historic order, there's Clojure. Clojure is a Lisp derivative, so it has a programming style very different from languages you'd otherwise know, and it burns through a lot of parentheses! But Clojure runs on the JVM, is very compatible with all the rest of Java, and it's dynamically typed. You can use it as a scripting language or treat it like a compiled language... it's up to you. I find it fun to program in, and the fact that it's an almost pure functional language forces you to think in new ways about programming. It hurts your head at the beginning, but if you survive it's a very worthwhile exercise because you learn some techniques that will become more relevant (I think) in future programming.
In summary, it would probably do you good (put hair on your chest, if I may be so sexist) to learn one or more of these "alternative" / "scripting" languages. You may find them useful. Usually when there's something to be hacked up quickly in my project, I get the job because all my colleagues only know Java, and by the time they finish setting up their class framework I'm already done.
Quote:
so why don´t I just stick with java
and be good at ONE language instead of
having to switch between 2 languages
and their syntax.
This seems like a more general question about learning programming languages than learning a new language (Groovy) which runs on top of the Java Virual Machine.
Here's a question:
Suppose you are learning a foreign language because you want to be fluent in multiple languages so you can converse with many people. You're learning German right now, but you're getting good at it, but you also want to learn Spanish. Would you just suddenly forget German if you start to learn Spanish? If you are indeed worried that you will, what would you do?
If you were going to learn Groovy, but don't want to forget how to write Java, then why not continue to use both languages at the same time?
One of the things about being a programmer is going to be learning to adapt to new technologies as they come along. It's a good thing to be able to learn new languages, as it's going to be a skill that's going to be very useful in a field which is constantly changing.
Why don't you code your desktop apps in groovy too? Just because groovy is the choice of a web framework (grails) doesn't mean that you can't use it for desktop apps.
Indeed, it is great for desktop apps too. It's more a matter of dynamic or static languages...
In my opinion, it is quite good to have for each task the right language at hand. So go ahead and learn groovy - the result will be that you'll miss groovy features when you try to use java again ;-)
I would say in general in this field it's always good to be learning. I try constantly to learn new concepts to add to my toolbox, while getting better at the core things I'm interested in like Java. I recently purchased a book on learning Clojure - another functional language for the JVM.
The downside to learning something without using it every day is that some details don't stick in your head. That said, I'm glad I spent some time with Clojure; the important stuff stuck and I know I can quickly look up the details if and when I need to. You may want to take a similar approach to Groovy.
The Java platform is slowly starting to change direction to one where the JVM is targeted by multiple source languages (a trick .net has been showing off since day 1, but it's taking Java a while to catch up there). The Java7 classfile format is even adding a new instruction to make these dynamic languages work faster.
If you want to keep yourself current, then learning Groovy is a good way to do it, without abandoning all your investment in the Java platform.
Furthermore, Groovy (and Grails) is now maintained by SpringSource, so its popularity is only going to increase.
Going from java to groovy isn't a lot of work. No where near what would be needed to move to a less Javaish language like clojure.
I really like groovy for one-off apps and for scripting existing java code. I've used it to parse data from REST calls and feed the data to a JMS queue. I've used it to create scrambled test data for a partner from our production data. For stuff like that it is amazing.
If the goal is to learn a dynamic language to add to the toolbox, Python and Ruby are both good choices. They run on the JVM and have native versions. Both are well supported on a large number of platforms.
If the goal is to learn an alternative JVM language, groovy is an excellent choice. Both Scala and Clojure would also be good choices.
I used to stick to the "learn a new language every year rule" from The Pragmatic Programmer, but that was before I had kids. Now I learn a new building toy every six months.
First of all I'm this is a highly subjective question.
In my humble opinion it is worth learning a new language especially if it varies in paradigms (as is the case with groovy). I'm fairly young myself so for me learning a new language is not a much of hassle but the way I see it if you like the language, you estimate that coding in language X will be profitable you should learn it.
It won't hurt your resume.
It won't make your head hurt (much).
The only problem is, will you use it. You need to use a language to become good at it. If you are going to learn it now and never use it tomorrow it probably ain't worth learning it.
Learning something new does not take away something you already know. You may be a bit rusty when you get back into Java, but it'll come back real quick.
Also--
I'm not a Java guy, but I believe Groovy targets the JVM. If this is the case, then programming in Groovy will make you a better Java programmer, because you'll still be targeting the same framework as Java (the language) so you'll still continue to gain experience with the Java libraries. Knowing the available libraries is what really matters, not how well you know every minute detail of a particular language.
I find that by learning new languages, I always end up learning new ways to think about problems. Each language guides you into solving problems in the way most easily expressed by the language. Learning new languages only makes you stronger all around because you learn new ways to solve problems.
You might have to re-orient yourself with the libraries after a long time away from a language, but even then it's not a huge ordeal - just more frequent google searches, etc.
The benefits, however, are worth it. I recently did some functional programming for the first time and it really taught me a lot of different ways to think about certain situations. I find myself now using some of C#'s functional aspects and it makes my code a lot cleaner in some cases. The bottom line is; if your going to do this for a living you are going to want to learn more than one language, have you ever met a mechanic that only knew one make and model of car?
It's always good to learn a new language to be a better programmer. Groovy is a natural choice for java programmer - easy to learn and you can still use your all java knowlege.
Groovy is a dynamic language, after try to learn any functional language (like Scala). With this experience you will see java from different perspecitve. Some task that was painful in Java will be trivial in Groovy/Scala.
you can program desktop aplication with Griffon whose language of choice is Groovy, give it a try
If you are looking for online help, check this websites:
for Groovy
for Grails

Studying standard library sources

How does one study open-source libraries code, particularly standard libraries?
The code base is often vast and hard to navigate. How to find some function or class definition?
Do I search through downloaded source files?
Do I need cvs/svn for that?
Maybe web-search?
Should I just know the structure of the standard library?
Is there any reference on it?
Or do some IDEs have such features? Or some other tools?
How to do it effectively without one?
What are the best practices of doing this in any open-source libraries?
Is there any convention of how are sources manipulated on Linux/Unix systems?
What are the differences for specific programming languages?
Broad presentation of the subject is highly encouraged.
I mark this 'community wiki' so everyone can rephrase and expand my awkward formulations!
Update: Probably didn't express the problem clear enough. What I want to, is to view just the source code of some specific library class or function. And the problem is mostly about work organization and usability - how do I navigate in the huge pile of sources to find the thing, maybe there are specific tools or approaches? It feels like there should've long existed some solution(s) for that.
One thing to note is that standard libraries are sometimes (often?) optimized more than is good for most production code.
Because they are widely used, they have to perform well over a wide variety of conditions, and may be full of clever tricks and special logic for corner cases.
Maybe they are not the best thing to study as a beginner.
Just a thought.
Well, I think that it's insane to just site down and read a library's code. My approach is to search whenever I come across the need to implement something by myself and then study the way that it's implemented in those libraries.
And there's also allot of projects/libraries with excellent documentation, which I find more important to read than the code. In Unix based systems you often find valuable information in the man pages.
Wow, that's a big question.
The short answer: it depends.
The long answer:
Some libraries provide documentation while others don't. Standard libraries are usually pretty well documented, whether your chosen implementation of the library includes documentation or not. For instance you may have found an implementation of the c standard library without documentation but the c standard has been around long enough that there are hundreds of good reference books available. Documentation with hyperlinks is a very useful way to learn a new API. In any case the first place I would look is the library's main website
For less well known libraries lacking documentation I find two different approaches very helpful.
First is a doc generator. Nearly every language I know of has one. It basically parses an source tree and creates documentation (usually as html or xml) which can be used to learn a library. Some use specially formatted comments in the code to create more complete documentation. JavaDoc is one good example of this. Doc generators for many other languages borrow from JavaDoc.
Second an IDE with a class browser. These act as a sort of on the fly documentation. Some display just the library's interface. Other's include description comments from the library's source.
Both of these will require access to the libraries source (which will come in handy if you intend actually use a library).
Many of these tools and techniques work equally well for closed/proprietary libraries.
The standard Java libraries' source code is available. For a beginning Java programmer these can be a great read. Especially the Collections framework is a good place to start. Take for instance the implementation of ArrayList and learn how you can implement a resizeable array in Java. Most of the source has even useful comments.
The best parts to read are probably whose purpose you can understand immediately. Start with the easy pieces and try to follow all the steps that are hidden behind that single call you make from your own code.
Something I do from time to time :
apt-get source foo
Then new C++ project (or whatever) in Eclipse and import.
=> Wow ! Browsable ! (use F3)