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 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.
Much of the current users guide just links to the JavaDoc instead of
actually explaining the usage and giving examples. 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.
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.
Another thing that would help learning is to make the task APIs simpler:
- Inline the option classes into the task classes. I don't think there's
any good reason for the options to be separate objects.
- Be ruthless with options. We don't really need to support every single
option that the corresponding ant tasks do. Many of them are work
arounds for weak models anyway.
- Consistency. Make sure the methods and types for a given configuration
(eg including or excluding source files) are the same across all tasks.
Extract subclasses or interfaces for common configuration.
- Reuse configuration across tasks, by extracting domain objects and
moving the configuration to the model.
Adam
---------------------------------------------------------------------
To unsubscribe from this list, please visit:
http://xircles.codehaus.org/manage_email
