Correct Use of the 'tap' Method

[Adam George]

Hi,

I'm relatively new to Buildr/Ruby and whilst I'm getting the hang of most
things there is still one thing that I don't understand.

Consider this:

        # example 1 (seems to do nothing)
        task(:compile) do |task|
                task.sources = [path_to(:source, :main, :catalina)]
                task.with "org.apache.tomcat:tomcat-catalina:jar:7.0.35",
                        "javax.servlet:servlet-api:jar:2.5"
                task.into(_(:target, :classes, :catalina))
        end

... and this:

        # example 2 (works as expected)
        task(:compile).tap do |task|
                task.sources = [path_to(:source, :main, :catalina)]
                task.with "org.apache.tomcat:tomcat-catalina:jar:7.0.35",
                        "javax.servlet:servlet-api:jar:2.5"
                task.into(_(:target, :classes, :catalina))
        end

Both code blocks receive a task argument that identifies itself as
"my_project:compile" when printed to the console, but I can't understand why
the enhancement in example 1 does nothing to the compile task of my_project.  

I'm comfortable with the fact that I need to use .tap, but I don't really
understand why it's necessary. If both functions are given the same argument
at run time, why does only the second example work?  What is happening in
example 1 in this case?

Thanks and regards,

Adam George