Steve Appling wrote:
While adding support for Ant's depend to the Compile task, I wanted to make sure that I updated the current documentation for compile options, but I don't think there is any. I can't find anything in the user guide, samples, javadoc, or groovydoc that specifies the options. You have to read the source, understand how AbstractOptions works, find the options in the ant task documentation, and find out which ones are mapped to different names in Gradle. Ugh.
I agree.
I mentioned this before, but didn't get any responses. I think that it would be easier to both use and learn Gradle if there was a clearer separation between tutorial and reference documentation. In the end, I think there should be completely different documents for this, but a good start would be to have an explicit reference section of the current users guide that documents all of the tasks.
A good idea. What else would go in the reference section?
Much of the current users guide just links to the JavaDoc instead of actually explaining the usage and giving examples.
This is really just us making use of the scarce documentation there already is, in the form of the API. I think we've been better in the last couple of releases at writing content, rather than simply point to the API.
Where there is an inheritance chain spanning both Groovy and Java source, this becomes very hard to follow because the JavaDoc and GroovyDoc aren't linked.
I think this is becoming less of a problem, as more groovy is replaced by java in the API. We should think perhaps about providing a java-only API for the tasks. We're pretty close to this anyway.
While I think that developers looking for a programmatic API should look at the JavaDoc, I don't think that typical writing of a build.gradle file should require more than the users/reference guide. I don't think that anyone should be required to look at the Ant documentation to understand how to use Gradle.
I agree. We absolutely still want decent API docs, because people writing build scripts are at the end of the day writing code against a programmatic API.
Adam --------------------------------------------------------------------- To unsubscribe from this list, please visit: http://xircles.codehaus.org/manage_email
