Adam Murdoch wrote:
On 22/02/10 8:47 PM, Nacho Coloma wrote:
I am getting best results combining the user guide with the javadocs.
It's easier if you think about gradle as "programming" (go search for
the API, see what's there, stretch my groovy) instead of "using ant".
The user guide is good for introducing concepts, but in the end it's
easier if you understand what are you doing when you write "task 'foo'
<< "
On the contrary, if you are used to ant/maven, you will try to use the
user guide as a "list of tags and attributes available", which it is
not.
My .02 euro.
I think this is a really important point. Perhaps we should add a
comment like this to the tutorials. Ultimately, writing a build script
is about writing code to drive an API. It's not a config file. And
although we want to (and do) document a lot of the API in the user
guide, the Javadoc will always be the only complete reference to the API
(the code is too, I guess).
One thing the user guide could do to help is give the reader a much
clearer idea of how the DSL maps to the API, and where to find the
Javadoc for a given element in the DSL. For example, we assume a lot
about the reader's knowledge of Groovy, but I suspect almost everyone
who is new to Gradle is also new to Groovy. The user guide could help
these readers separate the Groovy magic from the Gradle magic.
Amen. I don't know how many times I've resorted to println()ing an
object in the build.gradle just to see what implementation it was so I
could go look up the source.
I agree that the Javadoc can be useful when it happens to be fully
fleshed out and easily linked (more judicious links in the user guide
might also be useful)... but perhaps there is also some room in the user
guide for some more straight-forward references for certain things. I
don't know.
I do agree that some of the (even simpler) concepts could be explained
better. It took three full reads through the manual and many hours of
goofing around for me to "get it" some of the time. And I'm still not
confident enough to think I know enough to explain it to others. :)
-Paul
---------------------------------------------------------------------
To unsubscribe from this list, please visit:
http://xircles.codehaus.org/manage_email
