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.
Sorry for the rant, but this has been bugging me since we started using Gradle.
The lack of documentation made it MUCH harder to get started. I'm willing to
get a reference section started in the user guide, but want some consensus on this.
Here is what I propose:
1) Add a task reference section to the users guide.
2) Move some of the detailed information about specific tasks from the various
plugin sections to the reference section. Keep general usage, examples, and
plugin specific information (like conventions) in the plugin section.
3) Document all options explicitly in the reference section. Don't require a
user to look at source, JavaDoc, or Ant documentation.
--
Steve Appling
Automated Logic Research Team
---------------------------------------------------------------------
To unsubscribe from this list, please visit:
http://xircles.codehaus.org/manage_email
