Is there any way to automate some of the configuration docs? One of the things
I like about maven is the automatic documentation of all the plugin parameters
during the site generation. The documentation is extracted from the javadoc
comments. Is there anything similar to this in groovy/gradle?
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.
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.
---------------------------------------------------------------------
To unsubscribe from this list, please visit:
http://xircles.codehaus.org/manage_email
