+1 to stronger links between javadoc and user guide. I also had to read the user guide several times to get it, and I still don't know what I am doing (groovy-wise) with some config magic.
On Tue, Feb 23, 2010 at 9:58 PM, Paul Speed <[email protected]> wrote: > > > 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 > > > --------------------------------------------------------------------- To unsubscribe from this list, please visit: http://xircles.codehaus.org/manage_email
