Paul Gier wrote:
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?
This is a good option. We could use something like a custom doclet to do
this, for the java parts of our API. There is, for example, a docbook
doclet (http://www.michael-a-fuchs.de/) which we could use to spit out
docbook to include in the userguide.
We could probably put something together for the groovy parts of the
API. It might be easier to convert the API to java.
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
---------------------------------------------------------------------
To unsubscribe from this list, please visit:
http://xircles.codehaus.org/manage_email
